知識庫 / 開發者

API 概覽

你在應用程式中使用的模型、生成器和餘額，皆來自於你自己的代碼。 API 採用 OpenAI 與 Anthropic 的格式，因此大多數工具和 SDK 只要更改基本 URL 與金鑰即可使用。

為了方便起見，此頁面是機器翻譯的。英文原件為適用版本。

什麼是 API

一個在上的 HTTP API nymbot.ai 能回答與 OpenAI 或 Anthropic 用戶端已經發送的相同請求。您會得到：

• 聊天補全, 該 回應 API 和 Anthropic 訊息，包含串流、工具、圖片、 推理和網頁搜尋，適用於系列中的每個模型 目錄 以及用於 Nymbot 自身的自動路由。
• 圖片, 影片, 演講, 逐字稿 和 嵌入.
• 你的 平衡, 閃電儲值, 從您的錢包自動儲值 和一個 歷史 每次請求的成本是多少。

它是從同樣的兩個中支付的。 餘額 與應用程式相同， 價格也完全一致。API 沒有訂閱制，也沒有免費額度：每一筆請求都 必須使用您購買的點數來支付。

這套 API 並不會加入任何 Nymbot 自身的內容。您的訊息會依照您發送的原樣傳送到模型：沒有 Nymbot 的系統提示詞、沒有記憶、沒有日期或語言提示。回傳的內容僅包含模型的回答以及所產生的成本紀錄。

基礎 URL

每個端點都位於 /api/v1/. 一條未知的路徑返回 404 且一個 使用錯誤方法呼叫的已知路徑會回傳 405，皆為 JSON 格式。

該 API 會回應來自任何網站的跨來源請求，因此瀏覽器頁面可以呼叫它。然而，任何你發送到瀏覽器的內容，任何開啟它的人都能讀取，因此請務必僅使用權限較小的金鑰來執行此操作 蓋子以您的 nym（金鑰、帳戶摘要、NWC 自動儲值與退款兌換）簽署的端點除外：在瀏覽器中，它們僅回應 Nymbot 自己的網站。請參閱 簽署帳戶請求.

將每個 JSON 內容發送至 Content-Type: application/json. 任何其他類型都將 被拒絕，錯誤訊息為 415，所以是一個純 HTML 表單或是 text/plain 來自另一個網站的請求無法存取 API。使用 cURL 傳遞 -H "Content-Type: application/json" 連同 -d.

API 金鑰

金鑰是在應用程式中製作的。開啟 API 在 Web 應用程式的側邊欄中，或在 Android 與 iOS 的選單中，然後點擊 建立金鑰. 給它一個名稱，如果你願意， 一個上限和一個到期日。

金鑰僅會顯示一次。在關閉工作表之前，請將其複製到安全的地方：Nymbot 僅保留其指紋，因此無法再次向您顯示。遺失的金鑰無法找回；請將其撤銷並重新製作一個。

一把鑰匙看起來像 sk-nymbot- 接著是 43 個字母、數字、連字號及 底線。應用程式會以名稱及簡短提示列出每個金鑰，例如 sk-nymbot-Qm7x…c2Lw.

• 一把密鑰屬於你的 nym。 它會消耗您的餘額，且只有您的 nym 可以 建立、變更或撤銷它。任何持有密鑰的人都可以使用它進行消費，因此請將其視為 密碼。
• Caps 在 sats 裡。 金鑰可以設置支出上限，且該上限可以在每天、每週（週一）或每月（每月一號）的 00:00 UTC 進行重置。它會同時計算兩種餘額，標準點數計為 10 sats，Pro 點數計為 100，因此無論請求消耗哪種餘額，結果都是相同的。在請求執行之前，系統會將該請求可能產生的最高費用（向上取整至整數點數）與剩餘的上限進行比對。如果餘額不足以支付，請求將被拒絕，錯誤訊息為 403 key_limit_reached，即使 答案原本會在上限內；該錯誤會顯示剩餘多少量以及上限何時 重置。降低 max_tokens 降低了那種最壞情況。請求將按實際成本計費並計入上限，因此，如果提供者回報的 token 數量超過了預留數量，最後一個符合條件的請求可能會使金鑰稍微超出其上限；隨後的請求則會被拒絕。
• 耗盡的錢包只會停止花錢。 即使密鑰達到上限，仍可檢查餘額、查看歷史紀錄、列出模型、計算 Token 數量、儲值，並查看已開始的影片。
• 到期時間為選填。 在您設定的日期之後，金鑰將停止運作。
• 撤銷是即時且最終的。 被撤銷的金鑰在下次請求時會失敗。 它會保留在清單中並標記為已撤銷，因此其支出歷史紀錄仍能保持合理。
• 您最多可以擁有 25 個有效金鑰，每個金鑰都有自己的名稱。更改金鑰的重設週期將從零開始計算一個新的週期。

同一張表格顯示了每個金鑰在此期間及總共的支出、最後使用時間、您的兩個餘額，以及您最近的 API 請求。其背後的端點文件記載於 管理金鑰.

驗證請求

請在下列任一標頭中傳送金鑰。它們是等效的，因此請使用您的用戶端預設傳送的任何一個：

遺失、未知、已撤銷或已過期的金鑰將返回 401，附上代碼 missing_api_key, invalid_api_key, revoked_api_key 或者 expired_api_key列出模型、音訊模型與聲音，以及付款方式 不需要金鑰。

圖片、影片、語音、逐字稿和嵌入向量也可以透過 Lightning 每次支付一個請求的費用，完全不需要金鑰：在不附帶金鑰的情況下發送請求，並在...支付發票。 402 回答。看 無需金鑰按次付費.

金鑰管理、帳戶摘要和自動儲值是例外：它們使用的是來自您 nym 的簽章而非金鑰，因此洩漏的金鑰無法製造更多金鑰。請參閱 簽署帳戶請求.

您的第一個請求

將金鑰放入環境變數中，然後詢問模型。這些頁面中的範例都是從中讀取的 NYMBOT_API_KEY.

cURL

export NYMBOT_API_KEY="sk-nymbot-..."

curl https://nymbot.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $NYMBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nymbot/auto",
    "messages": [{"role": "user", "content": "What is a Lightning invoice?"}]
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://nymbot.ai/api/v1",
    api_key=os.environ["NYMBOT_API_KEY"],
)

reply = client.chat.completions.create(
    model="nymbot/auto",
    messages=[{"role": "user", "content": "What is a Lightning invoice?"}],
)
print(reply.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://nymbot.ai/api/v1",
  apiKey: process.env.NYMBOT_API_KEY,
});

const reply = await client.chat.completions.create({
  model: "nymbot/auto",
  messages: [{ role: "user", content: "What is a Lightning invoice?" }],
});
console.log(reply.choices[0].message.content);

nymbot/auto 是 Nymbot 自己的路由，從標準餘額中支付。請在那裡放入目錄模型的 id，例如： anthropic/claude-sonnet-5，使用 Pro 餘額中的該模型。 列出模型 提供每個 ID。

一次請求的費用是多少

API 的計費方式與應用程式完全相同。

• 哪種餘額？ nymbot/auto 花費了 標準 餘額 (10 sats 貸記)。其他每個聊天模型都花費了 專業 餘額 (100 sats 額度)。標準圖像生成器與 標準語音消耗標準額度；其他所有生成器皆消耗 Pro 額度。Embeddings 消耗 標準額度。轉錄功能在標準餘額足以支付時消耗標準額度， 否則消耗 Pro 額度。模型列表會說明每個模型 消耗哪種額度。
• 多少錢。 聊天請求根據模型實際讀取和寫入的 token 數量，並按供應商公布的費率進行計費。該價格會加上 5% 的費用，然後乘以 1.5，因此您支付的價格是供應商掛牌價格的 1.575 倍。價格會根據即時比特幣價格轉換為 sats，並以千分之一 credit 的單位進行計費。專業圖片、影片和語音的定價方式分別為每次生成、每秒或每個字符，逐字稿則按每秒音訊計費，並採用相同的費用和利潤率。標準圖片為固定的 5 個標準 credit，標準語音則為固定的 3 個。
• 最小值。 每一次計費請求的執行成本至少為 0.05 credit： 標準餘額扣除半個 sat，Pro 版本扣除 5 sats。credit 的小數部分會結轉， 而非每次都進位取整。
• 暫停，然後定下來。 在請求執行之前，系統會根據您發送的內容以及可能產生的最大 token 數量，從您的餘額中預扣最高可能產生的費用。非純 ASCII 的文字將按其 UTF-8 字節計算大小，而 ASCII 數字和標點符號各計為一個 token，因此任何字體、程式碼和數字都會被全額預扣。預扣金額以整數積分計算，且至少為一個積分，因此任何請求至少需要在標準餘額中有 10 sats，或在 Pro 帳戶中有 100 sats 才能開始。最終僅會收取實際費用；其餘預扣金額將在請求完成時釋放。長請求的預扣時間將與其執行時間相同；如果預扣的積分因故變得無法使用，串流將會隨著 a 402 insufficient_balance 錯誤事件，且產生的費用將會被收取。若實際費用 超過餘額可支付的範圍，則會扣除全部餘額，其餘部分則為欠款 (owed_sats 在 nymbot （對象，以及負餘額）。欠款將首先從下一次到達該餘額的入帳中扣除。在欠款清償之前，該餘額中的任何金額都無法使用：無論是透過 API、應用程式內的回覆、轉帳或禮物。
• 餘額不足。 如果餘額不足以支付預留款項，請求將以以下方式被拒絕： 402 在任何程式執行之前。錯誤會顯示哪個餘額不足、 請求需要多少 sats 以及有多少可用餘額。較小的 max_tokens 意指更小的容量。
• 失敗。 一個失敗的請求不會產生任何費用，除非提供者對其在失敗前所完成的工作進行了計費，或者進行了網路搜尋或 nymbot/auto 任務 檢查是否已經執行；如果是，那就是您需要支付的費用，至少為 0.05 credit。您切斷的串流將根據提供者回報的 token 進行計費：Nymbot 在您離開後會繼續讀取提供者的串流長達 25 秒，以獲取該計數。如果未能收到，則根據您發送的內容和已寫入的內容進行估算，對於具有推理能力的模型，這將包括該次保留的所有輸出額度。連線中斷的請求仍會完成並進行計費。
• 網路搜尋 每次搜尋花費 0.008 美元，轉換為 sats，每當搜尋 執行時，無論模型隨後回答還是失敗。它所閱讀的頁面也會作為輸入發送給 模型，因此它們會增加其 tokens。

每個回應都會說明其成本。JSON 回應帶有一個 nymbot 包含 付款時使用的餘額、以 credits 和 sats 計的費用，以及剩餘金額的物件：

成本對象

"nymbot": {
  "balance": "pro",
  "charged_credits": 0.162,
  "charged_sats": 16.2,
  "balance_credits": 412.425,
  "balance_sats": 41242.5
}

付費回應也包含這些標頭，這就是尋找非 JSON 格式（例如語音）回應成本的地方：

每百萬個 token 的費率，已包含費用與利潤，位於 模型列表 以美金和聰（sats）計算，並且在 價格表如果無法讀取比特幣價格， 付費請求將返回 503 price_unavailable 與 Retry-After: 60 與其瞎猜。

錯誤

每個錯誤都有相同的樣貌，即 OpenAI 客戶早已熟悉的那個樣貌。 code 是一個你可以進行比對的穩定名稱； message 是為人們而設，且可能會變動。

錯誤主體

{
  "error": {
    "message": "This request needs up to 200 sats (2 credits) on your Pro balance, and 40 sats are free. Catalog models spend the Pro balance. Top up in the Nymbot app or with POST /api/v1/topup/create/btc-lightning.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance": "pro",
    "required_sats": 200,
    "balance_sats": 40
  }
}

兩個例外：

• /api/v1/messages 以 Anthropic 的錯誤格式提供答案，因為那是 Anthropic 客戶端解析的格式： {"type": "error", "error": {"type": "authentication_error", "message": "…"}}. 類型隨狀態而定： invalid_request_error, authentication_error, billing_error (402), permission_error, not_found_error, request_too_large, rate_limit_error, api_error 或者 overloaded_error (503).
• 在第一個位元組傳送之前就失敗的串流請求會得到一個包含上述狀態的普通 JSON 錯誤，而非事件流。串流開始後的失敗則會以該端點自身格式作為串流的最後一個事件發送。

錯誤訊息絕不包含其他服務的內部細節。提供者的錯誤訊息在傳遞給您之前，都會經過重新措辭。

限制

圖片連結必須指向公開主機：指向私有或區域網路位址， 或是 Nymbot 自身網站的位址都會被拒絕。適用於應用程式的供應商節流機制也同樣適用於此，因此對單一供應商發送的突發請求可能會被減速，而非直接失敗。

API 可以看到什麼

API 並不像應用程式那樣具有隱私性，而其具體差異值得精確說明。

• 這不是端對端加密。 在應用程式中，一則訊息會被密封在您的 裝置上，僅由 Nymbot 持有的金鑰進行加密，並以...的形式傳輸 禮物包裝. API 請求是普通的 HTTPS：它在前往 Nymbot 的途中是加密的，而 Nymbot 的伺服器會以明文方式讀取它以進行處理。
• 提示與回覆不會被儲存。 它們傳遞至模型， 答案傳回。保留下來的是帳單：針對每次請求，包含時間、模型、類型、 token 數量、成本、餘額、金鑰以及是否成功，保留期為 90 天，即為 查詢紀錄 向您展示。 同一個請求的使用紀錄（時間、類型、模型、token 數量、成本、持續時間以及是否使用了網路搜尋或是否成功）也會與應用程式本身的紀錄一起保留 90 天。
• 其他所有為 nym 持有的資產都很小，並列於此。 API 金鑰 以雜湊方式儲存，絕不儲存金鑰，並包含 其名稱、簡短提示、支出上限、重設週期、有效期、建立時間以及 上次使用時間；僅保留最新的 50 個已撤銷金鑰。An 自動儲值 錢包連接以加密方式儲存，包含其閾值、金額以及上次儲值結果。 影片作業將保留 24 小時。 按次計費的請求僅會保留 Lightning 支付雜湊值 7 天，以及一個加密的退款代幣 30 天，且與匿名性無關。 餘額不足以支付的費用將以欠款形式保留，直到透過儲值完成支付。
• 清除應用程式會將其刪除。 A 裝置清除 撤銷並刪除所有 API 金鑰，並 刪除查詢紀錄、使用記錄、錢包連接和影片作業。餘額 以及任何仍欠的費用仍保留在 nym 上。
• 模型的提供者會看到您的請求，正如它從應用程式中所做的那樣。目錄 模型在它們的製造者處運行；標準路由和嵌入在 Cloudflare 上運行。
• 生成的媒體是公開的。 以連結形式交付的照片和影片 是上傳到公開的 Blossom 檔案主機，檔案的位址即為其雜湊值。 任何擁有連結的人都可以開啟它，且 Nymbot 無法再次將其移除。請要求 b64_json 而且回應中會傳回一張 生成的圖片，且從未被上傳。
• 所以你提供的圖片是生成器嗎？ 你上傳到...的一張圖片 編輯，或者以...發送 data: 生成器中的 URL image_url, 會先上傳到公開的 Blossom 主機，以便生成器可以抓取它，同樣的情況也適用於它。由圖片傳送的 https:// 連結會以該連結的形式傳遞。聊天請求中的圖片會傳送到模型的供應商， 而不是 Blossom。
• 一個金鑰已與您的 nym 連結。 金鑰所花費的一切都會從你名稱的 餘額中扣除，因此使用 API 並非 匿名如果你想讓 API 使用與你日常使用的 nym 分開，請使用另一個具有獨立餘額的獨立 nym 來建立金鑰。

如果你需要應用程式提供的保護，請使用這些應用程式。API 是為了讓你能在自己的工具中使用模型時所設計的。

每個端點

“Nym” 指的是由您的 Nostr 金鑰簽署的請求，描述於 簽署帳戶請求. 對於已經支援這些格式的工具，請參閱 工具與 SDK，而對於如 Claude Code、Codex 和 Cline 等程式碼代理，請參閱 編程工具.