系統 API 用於管理 MixRoute 帳號中的資源,包括 API Key、智慧路由 Key 和錢包操作。它與模型推理 API 相互獨立。
系統存取權杖擁有帳號級管理權限。請勿將其放入瀏覽器程式碼、行動應用程式、日誌或原始碼儲存庫。
取得系統存取權杖
在 MixRoute 控制台開啟 帳號設定 → API 存取,生成並複製系統存取權杖,然後將其儲存到金鑰管理系統。
GET /api/user/token 會生成新的系統存取權杖。這是輪換操作,不是查詢操作,並會使舊權杖失效。日常自動化中不要呼叫該介面。
設定後續範例使用的環境變數:
數字使用者 ID 可在帳號設定頁面中檢視。
認證請求標頭
每個受保護的系統 API 請求都必須攜帶以下兩個請求標頭:
傳送 JSON 請求內容時,還需要:
使用者 ID 必須屬於該系統存取權杖。認證失敗不一定使用相同的 HTTP 狀態碼:缺少憑證或使用者 ID 不匹配時可能傳回 HTTP 401,而無效的系統存取權杖目前會傳回 HTTP 200 和 success: false。客戶端必須同時檢查 HTTP 狀態碼和回應結構。
可使用以下只讀請求驗證認證設定:
回應結構
多數系統 API 使用統一回應結構:
部分參數驗證和認證錯誤會傳回 HTTP 200 和 success: false,因此客戶端需要同時檢查 HTTP 狀態碼與 success 欄位。
額度單位
帳號餘額和 API Key 額度使用內部額度單位儲存,並不直接等於美元。請從公開狀態介面讀取目前換算係數:
換算公式如下:
quota_per_unit 是部署設定,可能發生變化。客戶端應動態讀取,不要寫死目前數值。
帳號餘額與 Key 額度
- 帳號餘額來自
GET /api/user/self 的 quota 欄位,是帳號可用的錢包餘額。
- Key 額度由
remain_quota 表示,是單個 API Key 的消費上限。
- 給 Key 設定額度不會從錢包中轉移或凍結資金。
unlimited_quota: true 只表示沒有 Key 級額度上限,請求仍會消耗帳號餘額。
讀取並換算目前帳號餘額:
可用分組
建立 Key 前,應讀取目前帳號可選擇的分組:
不要假設其他帳號的分組也對目前帳號開放。本教程中的通用範例使用 default 分組。
安全檢查清單
- 系統存取權杖只能儲存在伺服器端。
- 自動化任務應使用獨立帳號或獨立憑證。
- 不要記錄顯示完整 Key 介面的回應。
- 儘量為每個 API Key 設定明確名稱、過期時間、額度和 IP 限制。
- 輪換時先建立替代 Key,遷移流量後再停用並刪除舊 Key。