接入說明
使用系統存取權杖查詢帳戶資料, 餘額, API Key, 用量, 任務及帳單
中國大陸用戶請注意: 中國大陸用戶請使用 https://toapis.cn 作為接口地址 (Base URL). 文檔示例中的 https://toapis.com 請替換為 https://toapis.cn.
這組 GET 介面僅讀取目前帳戶的資料. 主帳戶不會自動取得子帳戶資料, 管理員也只能查詢自身. 帳戶查詢使用系統存取權杖, 與模型呼叫使用的 API Key 不同.
取得系統存取權杖
登入控制台, 在設定的系統存取權杖區域產生權杖. 重新產生會使舊權杖失效, 請同步更新既有整合. 本組查詢為唯讀, 但權杖在舊介面上仍保留原有權限, 並非嚴格的唯讀憑證.
每次請求僅傳送一個 Authorization 標頭. 不接受 cookie, URL 憑證, 模型 API Key, Agent 或 MCP 權杖代替身分, 不需要 X-User-Id. 選用 X-Locale 支援 en, zh, zh-TW, ja, ko, ru; 未提供有效值時使用帳戶偏好及語言協商規則.
curl --request GET \
--url 'https://toapis.com/api/v1/account' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'回應與金額
成功時為 HTTP 200, code=0, message="". 失敗保留實際 HTTP 狀態及數字錯誤碼. 請依 HTTP 狀態及 code 判斷, 不依賴可翻譯的 message. ID 及金額為字串, 時間為含時區的 RFC 3339, 未知或不適用的欄位依契約回傳 null.
餘額與用量同時提供 USD 及 credits, 以同一額度快照換算. 請採用回傳的 credits_per_usd, 不寫死舊餘額介面的換算值. 付款金額保留原幣別, 與 credits 分開處理.
回應包含 Cache-Control: private, no-store 及 X-Request-Id. 後者識別本次查詢, 與用量記錄中原生成請求的 ID 不同.
{"code": 0, "message": "", "data": {"items": [], "has_more": false, "next_cursor": null, "meta": {}}}分頁與時間範圍
清單統一回傳 data.items, has_more, next_cursor, meta. 空清單為 [], 最後一頁游標為 null. 將 next_cursor 原樣作為下一頁的 cursor, 保留原篩選條件, 不解析游標. 變更篩選後重新開始, 預設不計算總數.
時間依 UTC 半開區間 [from,to) 比較, 秒級資料的兩端邊界向上取整. from 與 to 成對提供, 用量查詢始終必填. 任務預設最近 24 小時, 最長 31 天; 儲值與發票預設最近 31 天, 最長 366 天. 預設區間在第一頁固定, 後續頁可繼續省略時間. 未知參數, 重複純量及錯誤跳脫均回傳 400.
限流與錯誤處理
每位使用者共用 120 次/分鐘, 用量彙總額外限制 6 次/分鐘, 發票清單與詳情另共用 6 次/分鐘. 收到 429 時依 Retry-After 退避並加入隨機抖動. Redis 無法使用時, 輕查詢降級為每節點每 IP 桶及每使用者各 30 次/分鐘, 彙總與發票回傳 503.
| HTTP | code | 處理 |
|---|---|---|
| 400 | 10004 / 13028 | 修正參數或游標, 不原樣重試. |
| 401 | 11032 / 11059 | 檢查系統存取權杖是否缺少, 無效或已輪換. |
| 403 | 11023 / 12001 / 12002 / 12006 | 檢查帳戶狀態與權限; 子帳戶不能讀取帳單. |
| 404 | 13001 | 資源不存在或不屬於目前帳戶. |
| 429 | 10002 | 依 Retry-After 退避. |
| 500 | 10000 / 13029 | 保留請求 ID 排查內部錯誤或換算設定. |
| 503 | 11001 / 13030 / 13032 | 退避; 用量查詢逾時可縮小時間範圍. |
| 409 | 15045 | 透過既有互動流程關聯帳單帳戶, 不原樣重試. |
| 503 | 15046 / 15047 | 退避或聯絡支援檢查 Stripe 設定及 Customer 對應. |
{
"code": 10004,
"message": "Invalid query parameters.",
"data": {
"param": "limit",
"request_id": "request_example_query"
}
}資料範圍
用量為可變的消費記錄快照, 結算與退款可能更新舊記錄, 並非完整淨支出帳本. 任務僅回傳持久化中繼資料及可確認帳務, 不回傳結果, 不主動輪詢, 結算或退款. 儲值不包含人工贈送及獨立線下退款. 發票僅涵蓋目前已驗證的 Stripe Customer.
| GET | 使用說明 |
|---|---|
/api/v1/account | 取得帳戶資料 |
/api/v1/account/balance | 查詢帳戶餘額 |
/api/v1/account/api-keys | 列出 API Key |
/api/v1/account/api-keys/{api_key_id} | 取得 API Key 詳情 |
/api/v1/account/usage/records | 查詢用量明細 |
/api/v1/account/usage/summary | 查詢用量彙總 |
/api/v1/account/tasks | 列出帳戶任務 |
/api/v1/account/tasks/{task_id} | 取得帳戶任務詳情 |
/api/v1/account/billing/topups | 列出儲值訂單 |
/api/v1/account/billing/topups/{trade_no} | 取得儲值訂單詳情 |
/api/v1/account/billing/payment-method | 查詢付款方式 |
/api/v1/account/billing/auto-topup | 查詢自動儲值設定 |
/api/v1/account/billing/invoices | 列出發票 |
/api/v1/account/billing/invoices/{invoice_id} | 取得發票詳情 |
與現有介面的區別
現有權杖餘額, 使用者餘額及建立權杖保留各自契約. 本組 API 使用系統存取權杖及 code/message/data 回應, 不與舊介面混用. 帳戶任務查詢不取代生成結果查詢.