ToAPIsToAPIs

接入方式

公共 API 用於讀取目前帳戶的資料及管理自有的一般模型 Key. 主帳戶不會自動取得子帳戶資料, 管理員也只能操作自己的資源.

公共 API 用於讀取目前帳戶的資料及管理自有的一般模型 Key. 主帳戶不會自動取得子帳戶資料, 管理員也只能操作自己的資源.

國際版使用 https://api.toapis.com, 中國大陸版使用 https://api.toapis.cn. 這兩個網址是 API 入口, 請勿使用網站根網域呼叫這組介面.

取得系統存取權杖

登入帳戶設定, 在 "系統存取權杖" 中產生憑證. 重新產生會使舊權杖失效, 請同步更新整合設定.

所有請求在 Authorization 標頭中攜帶 Bearer YOUR_SYSTEM_ACCESS_TOKEN, 每次請求只傳送一個 Authorization 標頭. 不能用模型 API Key (sk-...), cookie, URL 憑證或 Agent/MCP 權杖代替身分, 也不需要 X-User-Id.

注意系統存取權杖可執行 Key 寫入操作, 不是唯讀憑證.

可選標頭 X-Locale 支援 en, zh, zh-TW, ja, ko, ru; 未提供有效值時使用帳戶語言偏好及協商結果, 查詢不會初始化帳戶偏好. 判斷結果請用 HTTP 狀態碼和數字 code, 不要比對可能隨語言變化的 message.

curl https://api.toapis.com/api/v1/account \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

回應與金額

所有回應只有 code, message, data 三個頂層欄位. 成功時 code=0, message="". HTTP 狀態碼: 一般成功為 200, 建立 Key 為 201, Webhook 測試入列與檔案刪除請求受理為 202.

失敗時保留真實 HTTP 狀態碼, 錯誤 data 只包含 param, params, request_id 或 null, 不暴露內部錯誤細節.

資源 ID 和金額統一用十進位字串表示; Webhook 的 api_key_id 使用整數; 時間為含時區的 RFC 3339 格式, 未知或不適用的值依欄位約定回傳 null. 餘額與用量同時提供 USD 和 credits, 以回應中的 credits_per_usd 為換算基準; 支付金額保留原幣別.

所有回應帶 Cache-Control: private, no-store 和 X-Request-Id 標頭. X-Request-Id 標示本次 API 請求, 與用量 trace 中原生成請求的 ID 不是一回事.

{
  "code": 0,
  "message": "",
  "data": {
    "items": [],
    "has_more": false,
    "next_cursor": null,
    "meta": {}
  }
}

分頁與時間範圍

使用者檔案清單除外, 清單統一回傳 data.items, has_more, next_cursor 和 meta. 空清單 items 為 [], 最後一頁 next_cursor 為 null, 不回傳總數. 翻頁時將 next_cursor 原樣作為 cursor 傳入並保持原篩選條件; 修改篩選條件後要重新從第一頁開始.

時間範圍統一使用 UTC 半開區間 [from, to), 秒級儲存的邊界向上取整. 各介面的預設區間和上限不同: 用量查詢每頁都必須提供 from 和 to, 最長 31 天. 任務預設近 24 小時, 最長 31 天. 儲值和發票預設近 31 天, 最長 366 天. 預設區間在第一頁確定後固定, 翻頁時可以繼續省略.

未知參數, 重複參數或錯誤跳脫回傳 400.

速率限制與錯誤處理

讀取請求按使用者共用每分鐘 120 次的額度. 用量彙總, 發票及定價查詢各有每分鐘 6 次的額外限制, 發票清單與詳情共用同一額度.

API Key, Webhook 與使用者檔案寫入共用每使用者每分鐘 10 次的額度, 不占用讀取額度. 重新產生系統存取權杖不會重置限制, 新舊相容路徑也共用對應額度.

請求過於頻繁或同時傳送過多請求時可能回傳 429, 請依 Retry-After 加隨機延遲退避. 收到 503 表示服務暫時無法使用, 請降低頻率後重試. 建立, 輪替或刪除請求逾時後, 請勿盲目重送.

HTTPcode處理方式
40010001 / 10004 / 13002 / 13028 / 16014修正主體, 參數或游標.
40111032 / 11059檢查系統存取權杖.
40311023 / 12001 / 12002 / 12006 / 13003檢查帳戶狀態, 資源權限及 Key 群組.
40413001 / 16008資源不存在或不屬於目前帳戶.
40913004 / 13005 / 13006 / 15045 / 16015 / 16016處理 Key 上限, 到期, 額度或帳單關聯條件.
42910002依 Retry-After 退避.
50010000 / 13029保留 request_id 供調查.
50311001 / 13030 / 13032 / 13035 / 15046 / 15047 / 18028 / 18029退避, 必要時縮小用量區間.

資料範圍

主帳戶只能看到自身資料, 不包含成員 (子帳戶) 資料; 子帳戶不能讀取帳單. 用量記錄是消費日誌的即時快照, 會隨後續結算和退款變化, 不等於最終淨支出. 任務介面只回傳持久化的任務中繼資料和可確認的帳務, 不回傳生成結果, 也不會主動輪詢上游, 執行結算或發起退款. 儲值記錄不包含人工贈送額度和獨立的線下退款; 發票僅涵蓋目前已驗證的 Stripe Customer.

Key 的資源 ID 使用清單或詳情中的數字 id, 不能使用密鑰字串 (sk-...). 完整密鑰只在建立和輪替回應中回傳一次, 之後所有讀取介面都不再回傳. 寫入成功表示設定已儲存, 生效可能有短暫延遲. 停用, 輪替或撤銷 Key 可能使正在進行的請求或任務失敗: 系統不會自動取消任務或退款, 也不提供新舊密鑰的並行有效期.

介面目錄

以下為主要路徑. 相容期內的舊 /api/v1/account/... GET 路徑及舊介面遷移方式見 變更歷史.

使用者檔案介面管理已登記檔案, 自訂保留期及非同步刪除請求. 檔案清單為分頁例外: 僅回傳 items, next_cursor, 最後一頁游標為 "", 沒有 has_more 或 meta. 刪除請求受理回傳 HTTP 202. 設定保留期及刪除請求共用帳戶寫入預算; 使用者期限需平台自動清理開啟, 手動刪除不受此開關影響. 範圍與範例見下方使用者檔案介面.

HTTP
GET /api/v1/account取得帳戶資料
GET /api/v1/account/balance查詢帳戶餘額
GET /api/v1/api-keys列出 API Key
GET /api/v1/api-keys/{api_key_id}取得 API Key 詳情
GET /api/v1/api-keys/{api_key_id}/balance查詢 Key 餘額
POST /api/v1/api-keys建立 API Key
PATCH /api/v1/api-keys/{api_key_id}更新 API Key
DELETE /api/v1/api-keys/{api_key_id}撤銷 API Key
POST /api/v1/api-keys/{api_key_id}/rotate輪替 API Key
GET /api/v1/webhook查詢 Webhook 設定
PATCH /api/v1/webhook更新 Webhook 設定
POST /api/v1/webhook/rotate-secret輪換 Webhook 簽章金鑰
POST /api/v1/webhook/test測試 Webhook
GET /api/v1/webhook/events列出 Webhook 事件
GET /api/v1/webhook/events/{event_id}查詢 Webhook 事件
GET /api/v1/usage/records查詢用量明細
GET /api/v1/usage/summary查詢用量彙總
GET /api/v1/tasks列出帳戶任務
GET /api/v1/tasks/{task_id}取得帳戶任務詳情
GET /api/v1/billing/topups列出儲值訂單
GET /api/v1/billing/topups/{trade_no}取得儲值訂單詳情
GET /api/v1/billing/payment-method查詢付款方式
GET /api/v1/billing/auto-topup查詢自動儲值設定
GET /api/v1/billing/stripe/invoices列出發票
GET /api/v1/billing/stripe/invoices/{invoice_id}取得發票詳情
GET /api/v1/pricing查詢模型定價
GET /api/v1/user/file列出使用者檔案
GET /api/v1/user/file/retention查詢檔案保留期
PUT /api/v1/user/file/retention設定檔案保留期
POST /api/v1/user/file/deletion-requests建立檔案刪除請求
GET /api/v1/user/file/deletion-requests/{id}查詢檔案刪除進度

Webhook

接入順序:

  1. 呼叫 POST /api/v1/webhook/rotate-secret 產生簽章金鑰並儲存到接收端.
  2. 呼叫 PATCH /api/v1/webhook 設定回呼位址並啟用.
  3. 呼叫 POST /api/v1/webhook/test 傳送測試事件或查詢事件清單確認投遞結果.

驗章規則與完整步驟見查詢 Webhook 設定.

On this page