運作方式
Markdown請求在您的程式與模型之間如何處理。
完整指南
您向 Ailoot API 傳送請求的方式，與直接傳送至 OpenAI、Anthropic 或 Google 相同。Ailoot 會檢查金鑰與餘額，將請求轉交模型，以相同格式傳回回應，並依實際用量扣款。
一把金鑰 — 三種格式
格式由請求路徑決定，而非由模型決定。同一個 Claude 模型可透過 OpenAI Chat、OpenAI Responses 或 Anthropic Messages 呼叫，回應會採用您呼叫的路徑所對應的格式。
| 格式 | 路徑 | 使用此格式的用戶端 |
|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions | OpenAI SDK、大多數聊天應用程式與編輯器、n8n、LangChain |
| OpenAI Responses | /v1/responses | Codex CLI、OpenAI Agents SDK、新版 SDK |
| Anthropic Messages | /v1/messages | Claude Code, Anthropic SDK, Zed, Cline |
| Gemini | /v1beta/models/{model}:generateContent | Gemini CLI, Google GenAI SDK |
費用：保留金額與一次扣款
- 傳送新的文字請求前，Ailoot 會依輸入與一般回應的估計用量保留金額，並考量上限 (
max_tokens)與該模型的條件。若保留金額超過可用餘額或金鑰上限，只有確實遵守傳入上限的模型與方法，才能降低送出的上限，且不得低於 256 token 或規定的最低回應量。影像、影片與音訊的輸出，仍保留結果的完整費用。 - 回應後，依實際用量扣款一次。未使用的保留金額會立即退回餘額。
- 若回應費用高於保留金額，差額會從可用餘額中扣除。餘額永遠不會變成負數。
- 若連最低保留金額都不足，請求不會傳送，您會收到易懂的 402 錯誤，且不會扣款。
- 未產生結果的錯誤不會計費。
詳細說明與計算範例，請見此頁面：預留金額與扣款。
附有 Request ID 的錯誤
每個回應都會取得請求識別碼，顯示在標頭X-Request-ID及錯誤文字中。錯誤採用您呼叫的格式之 JSON，因此 SDK 能正確辨識。若發生問題，請將 Request ID 提供給客服 —讓我們能在一分鐘內找到請求。
{
"code": "API_KEY_REQUIRED",
"error": {
"code": "invalid_api_key",
"message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
"param": null,
"reason": "invalid_api_key",
"request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
"type": "invalid_request_error"
},
"message": "No API key was sent with the request. Nothing was charged. …"
}串流與逾時
串流回應 (stream: true) 以 Server-Sent Events 傳送。Ailoot 會在費用計算完成後傳回付費文字回應，因此使用stream: true時，格式仍是串流 (SSE)，但文字會在模型完成後以單一區塊傳回，而非逐字傳回。若回應準備時間超過約 15 秒，Chat Completions、Responses與Messages 串流會先傳送服務訊息: ping (約每 10 秒一次)，接著傳送: ailoot-charged-usd … ，其中包含扣款金額，最後傳送實際資料。SDK 會略過這類服務訊息。
Gemini 格式沒有服務訊息；此回應:streamGenerateContent會在費用計算完成後一次完整傳回。對推理模型，請預留足夠的用戶端逾時時間，等待幾分鐘屬正常情況。
回應標頭
X-Request-ID會出現在每個回應中。其他標頭則由 Ailoot 加入已付費的文字回應：
| 標頭 | 內容 |
|---|---|
X-Request-ID | 請求識別碼，客服會要求提供此值 |
X-Ailoot-Charged-USD | 此請求的扣款金額，以美元計價 |
X-Ailoot-Output-Tokens | 已付費的回應 token 數 |
X-Ailoot-Max-Tokens-Capped | 因餘額不足以涵蓋完整保留金額，而降低後的回應上限 |
X-Ailoot-Notice-Code，X-Ailoot-Notice | 回應因達到長度上限而停止時的說明 |
若串流已先傳送服務訊息，這些資訊會在實際資料之前以註解行傳送，而非放在標頭中。
提示詞快取
若模型支援快取，再次傳送較長的前綴 (系統指令、文件) 時，費用可能較低。快取讀取與寫入的價格，顯示於此處的模型資訊卡：目錄。是否命中快取，由模型開發者決定，Ailoot 不保證命中。