變更歷史
公共 API 的相容期舊路徑, 舊介面替代關係及遷移差異
2026-11-12
本次更新重新整理了公共 API 文件: 頁面現在按帳戶, API Key, 用量, 任務, 帳單和定價分組, 並補齊了 Key 生命週期 (建立, 更新, 撤銷, 輪替), Key 餘額和模型定價的介面文件. 原 "帳戶" 分組下的 5 個頁面已刪除, 舊文件網址會重新導向對應的新頁面. 本次只調整文件結構, 線上介面行為不變.
相容期舊路徑
下列 10 個 GET 舊路徑仍可使用, 行為與右側新路徑完全相同. 它們僅為相容保留, 將在後續版本移除, 請儘快遷移; 新整合請直接使用新路徑. 注意 /api/v1/account 和 /api/v1/account/balance 本身就是新路徑, 不在此列.
| 舊路徑 | 新路徑 |
|---|---|
/api/v1/account/api-keys | /api/v1/api-keys |
/api/v1/account/api-keys/{api_key_id} | /api/v1/api-keys/{api_key_id} |
/api/v1/account/usage/records | /api/v1/usage/records |
/api/v1/account/usage/summary | /api/v1/usage/summary |
/api/v1/account/tasks | /api/v1/tasks |
/api/v1/account/tasks/{task_id} | /api/v1/tasks/{task_id} |
/api/v1/account/billing/topups | /api/v1/billing/topups |
/api/v1/account/billing/topups/{trade_no} | /api/v1/billing/topups/{trade_no} |
/api/v1/account/billing/payment-method | /api/v1/billing/payment-method |
/api/v1/account/billing/auto-topup | /api/v1/billing/auto-topup |
Key 建立, 更新, 撤銷, 輪替, Key 餘額, Webhook, 定價和 Stripe 發票這些介面本身就沒有 /account 前綴的舊路徑, 只有新路徑.
舊帳戶介面遷移
下表是新舊介面的功能對應關係, 不是可直接替換的相容路徑: 兩邊的憑證, 參數和回應結構不同, 需要同步修改呼叫程式碼. 舊餘額和建立介面用模型 Key 認證, 新介面改用系統存取權杖; 舊用量介面還要求 X-User-Id 標頭, 新介面不再需要.
| 舊介面 | 新介面 | 遷移條件 |
|---|---|---|
GET /v1/balance, /balance | GET /api/v1/api-keys/{api_key_id}/balance | 使用系統存取權杖和 Key ID 查快照, 不以目標 Key 自身驗證. 無限剩餘額度為 null, 不用 -1. |
GET /api/usage/tokens/requests | GET /api/v1/usage/records | 參數及欄位遷移見下表. 快取讀取與寫入量位於 usage 物件內. |
GET /api/usage/tokens/summary | GET /api/v1/usage/summary?group_by=api_key | 明確傳 group_by=api_key. record_count 是紀錄行數, 不是完整請求數或最終淨支出. |
GET /v1/user/balance, /user/balance | GET /api/v1/account/balance | 讀取自己的帳戶餘額或子帳戶預算, 用十進位字串明確分開 USD 與 credits. |
GET /v1/pricing | GET /api/v1/pricing?api_key_id={api_key_id} | api_key_id 可指定 Key 視角. after/next_after 改為 cursor/next_cursor, 回應改用 code/message/data, 不是相同協定. |
POST /v1/tokens | POST /api/v1/api-keys | 請依建立文件的新欄位及型別遷移. 不接受 group, cross_group_retry 或 Webhook, 並非完整替代舊介面全部能力. |
舊 allow_ips 使用換行分隔的字串, 新介面改為字串陣列, 例如 ["192.0.2.10","2001:db8::1"]. 建立和更新介面都支援此欄位: 傳 [] 清除限制, 傳 null 或無效位址回傳 400. 只支援單個 IP 位址, 不支援 CIDR 網段.
用量欄位與分頁遷移
時間參數由舊 start_timestamp/end_timestamp (Unix 秒) 改為含時區的 from/to, 翻頁時保持同一時間範圍. token_id 改為 api_key_id 字串, page_size 改為 limit. 舊游標不能用於新介面.
快取欄位方面: 舊 cache_tokens 對應 usage.cache_read_tokens, cache_creation_tokens 對應 usage.cache_write_tokens. 新介面額外提供 5 分鐘和 1 小時寫入拆分, 拆分值已計入 cache_write_tokens, 不要重複相加.
欄位缺失或無效時回傳 null, 明確記錄的零回傳 0.
參數錯誤的 HTTP 狀態由 422 改為 400, 錯誤回應使用數字 code. 舊 quota 欄位是內部額度單位, 新 recorded_credits 已換算為 credits, 遷移時要調整金額口徑而不能只改欄位名.
| 舊欄位 | 新欄位 | 說明 |
|---|---|---|
log_id | id | 僅改名. |
token_id | api_key_id | 數字 ID, 以字串傳遞. |
token_name | key_name | 僅改名. |
model_name | model | 僅改名. |
start_timestamp/end_timestamp | from/to | Unix 秒 → 含時區的 RFC 3339; 翻頁時保持同一時間範圍. |
page_size | limit | 每頁條數. |
cost_usd | recorded_cost_usd | 該日誌列的入帳成本 USD, 十進位字串. |
quota | recorded_credits | 內部額度單位 → 已換算的 credits, 不能直接沿用舊數值. |
prompt_tokens | usage.input_tokens | 移入 usage 物件. |
completion_tokens | usage.output_tokens | 移入 usage 物件. |
reported_total_tokens | usage.reported_total_tokens | 上游回報的總 token 數; 移入 usage 物件. |
cache_tokens | usage.cache_read_tokens | 快取讀取量; 移入 usage 物件. |
cache_creation_tokens | usage.cache_write_tokens | 快取寫入總量, 已含 5 分鐘和 1 小時拆分, 不要重複相加. |
request_count | record_count | 日誌條數, 不是完整請求數. |
data[] | data.items[] | 記錄陣列移入 data.items. |
meta.has_more | data.has_more | 分頁資訊移入 data. |
meta.next_cursor | data.next_cursor | 翻頁游標; 舊游標對新介面無效. |
建立 Key 的欄位變化
| 舊欄位 | 新欄位 | 說明 |
|---|---|---|
expired_time | expires_at | Unix 秒 (-1 表示永不過期) 改為含時區的 RFC 3339; null 或省略表示永不過期. |
remain_quota/remain_credits | remaining_credits | 十進位字串, 保留精度. |
daily_credits/monthly_credits | daily_limit_credits/monthly_limit_credits | null 或 "0" 表示不限額. |
unlimited_quota | unlimited | 布林值, 不接受 null; true 時 remaining_credits 只能省略或為 null. |
model_limits_enabled | — | 已移除; model_limits 陣列非空即啟用限制. |
model_limits | model_limits | 逗號分隔字串 → 字串陣列; 拼接後最多 1024 UTF-8 位元組. |
allow_ips | allow_ips | 換行分隔字串 → 字串陣列; 僅單個 IP, 不支援 CIDR; [] 清除, null/無效位址回傳 400. |
行為變化: 建立成功的 HTTP 狀態由 200 改為 201, 完整密鑰從 data.key 回傳, 已含 sk- 前綴.
遷移後仍須區分的能力
帳戶任務介面只提供任務狀態和帳務中繼資料, 生成結果仍需使用原有的結果查詢介面. billing 和 usage 欄位的含義見實際費用與任務用量. 定價目錄只反映目前費率, 不能用來重新計算歷史帳單.
公共 API 的 Key 管理也不支援修改額度或恢復已撤銷的 Key.
Webhook 透過獨立的設定介面管理: 每個一般模型 Key 對應一份設定, 與 Key 的建立和更新是分開的操作. 詳見查詢 Webhook 設定.