接入方式
公共 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 表示服務暫時無法使用, 請降低頻率後重試. 建立, 輪替或刪除請求逾時後, 請勿盲目重送.
| HTTP | code | 處理方式 |
|---|---|---|
| 400 | 10001 / 10004 / 13002 / 13028 / 16014 | 修正主體, 參數或游標. |
| 401 | 11032 / 11059 | 檢查系統存取權杖. |
| 403 | 11023 / 12001 / 12002 / 12006 / 13003 | 檢查帳戶狀態, 資源權限及 Key 群組. |
| 404 | 13001 / 16008 | 資源不存在或不屬於目前帳戶. |
| 409 | 13004 / 13005 / 13006 / 15045 / 16015 / 16016 | 處理 Key 上限, 到期, 額度或帳單關聯條件. |
| 429 | 10002 | 依 Retry-After 退避. |
| 500 | 10000 / 13029 | 保留 request_id 供調查. |
| 503 | 11001 / 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
接入順序:
- 呼叫
POST /api/v1/webhook/rotate-secret產生簽章金鑰並儲存到接收端. - 呼叫
PATCH /api/v1/webhook設定回呼位址並啟用. - 呼叫
POST /api/v1/webhook/test傳送測試事件或查詢事件清單確認投遞結果.
驗章規則與完整步驟見查詢 Webhook 設定.