文件
管理 API
管理 Key 讓你自己的系統透過 API 建立、分組、限額和撤銷帳戶的 API Key,並讀取它們的花費。它不能呼叫模型。
適用情境
有些整合會給每個客戶、團隊或使用者各發一把 API Key,把每個客戶的 Key 放進一個分組,限制分組能花多少,再按 Key 或按分組讀回花費。Key 不多時,在 API 金鑰頁面操作就夠了;Key 多了,可以用管理 Key 讓指令碼或你自己的管理工具透過 API 完成同樣的事。
管理 Key 與 API Key 是兩種不同的憑證。API Key 能用的地方它不能用:它不能呼叫 /v1/chat/completions、/v1/messages 或任何其他模型路由,只能用於 /v1/management/,而 API Key 在那裡不起作用。
建立管理 Key
- 開啟 API 金鑰頁面,捲到頁面底部。在「管理 Key」下選擇「新增管理 Key」。這個區塊預設摺疊,開啟後才會顯示。
- 替 Key 取個名稱,例如 billing sync,這樣頁面就能說明每次變更是哪個程式做的。
- 填入允許呼叫它的位址,每行一個:可以是單一位址,如 203.0.113.7,也可以是位址範圍,如 203.0.113.0/24。沒有白名單時,任何拿到這把 Key 的人都能使用它;白名單留空時,對話框會提示你。
- Key 顯示出來時請立即複製。它只顯示一次:Kunavo 只儲存它的雜湊。
一個帳戶同時最多有兩把生效中的管理 Key。撤銷其中一把,才能再建立新的。
呼叫方式
把 Key 作為 Bearer 權杖傳送到 https://api.kunavo.com/v1/management。管理 Key 不接受來自瀏覽器的呼叫:它的回應不帶 CORS 標頭,所以其他網站上的頁面無法呼叫。Key 只應放在你的伺服器上,不要放進前端程式碼。
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"回應是 JSON。錯誤的格式與 API 的其他部分一致:一個 error 物件,包含 message、type、code,以及(在適用時)出錯的 param。你會遇到這些狀態碼:
| 狀態碼 | 含義 |
|---|---|
401 | Key 缺失、寫錯或已撤銷,或其帳戶已被停用或正在審核。 |
403 | 這把 Key 設了 IP 白名單,而請求來自不在名單上的位址。 |
404 | 分組或 Key 不存在、已刪除,或屬於其他帳戶。三種情況的回應完全一樣,所以拿其他帳戶的 id 來試探不會洩露任何資訊。 |
409 | 這次變更與帳戶目前的狀態衝突:分組名稱已被占用、Key 已撤銷,或帳戶已達到 500 把生效中 Key 的上限。 |
429 | 這把 Key 在最近一分鐘內已送出 60 次請求。Retry-After 回應標頭會告訴你要等多少秒。 |
分組
GET /v1/management/groups 列出帳戶的分組,附每個分組的月度上限和其中生效中的 Key 數。POST 建立分組,可帶選用的 monthly_limit_usd;名稱已被占用時回傳 409。PATCH /v1/management/groups/{id} 修改名稱或上限:傳送 null 表示不限,傳送 0 則暫停組內所有 Key 而不撤銷任何一把。DELETE 刪除分組,它的呼叫在用量頁面上仍保留它的名稱。它的 Key 保持生效並變為未分組;如果加上 ?revoke_keys=true,這些 Key 也會一併撤銷。
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001", "monthly_limit_usd": 50}'Key
GET /v1/management/keys 按建立時間從新到舊列出 Key。每頁 50 把,用 limit 可提高到 100。status 預設為 active,也可以是 revoked 或 all,group_id 則把列表限定到某一個分組。當 has_more 為 true 時,把 next_after 設為 after 即可讀取下一頁。列表中永遠不會出現 Key 的明文。
POST /v1/management/keys 建立一把 Key,需要名稱,可選 group_id、monthly_limit_usd 和 ip_allowlist。明文只在回應的 key 欄位裡出現一次。重複送出 POST 會建立第二把 Key,所以重試之前,請先列出 Key,查找這個名稱。
curl https://api.kunavo.com/v1/management/keys \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'PATCH /v1/management/keys/{id} 修改 Key 的名稱、分組、上限或白名單;把 group_id 設為 null 可把它移出分組。DELETE 撤銷它。撤銷已撤銷的 Key 不算錯誤。已撤銷的 Key 不能再修改。
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"用量
GET /v1/management/usage 回報整個帳戶在最長 90 個 UTC 日內的用量,GET /v1/usage 則回報單把 Key 的用量。group_by 接受 group、api_key、model 和 day 的任意組合,預設為 api_key。數字的含義與用量頁面一致:呼叫算在發生時 Key 所在的分組,失敗的呼叫不收費,某一時段的合計與同一時段 CSV 匯出的合計精確到分一致。group_id 和 api_key_id 把報告限定到某一個分組或某一把 Key。
curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"end_date 會視為今天,回應會回顯實際採用的結束日期。妥善保管
- 設定白名單。只能從你伺服器的位址使用的 Key,被人偷走後價值不大。
- 把 Key 放在執行你的工具的伺服器上的機密儲存空間裡。不要放進瀏覽器、行動應用程式或程式碼儲存庫。
- 如果洩露,請在 API 金鑰頁面底部撤銷它,或對它呼叫
DELETE。撤銷對話框還可以一併撤銷這把 Key 建立的 Key。 - 這把 Key 透過 API 做出的每一次變更,都列在 API 金鑰頁面的「管理 Key」下,附時間、來源位址和執行變更的 Key,保留最近 50 筆。在該頁面手動做的變更不在其中。
- 帳戶被停用或進入審核時,以及 Key 被撤銷時,Key 會自動失效。
一把管理 Key 每分鐘最多送出 60 次請求。每次變更送出一次請求,讀取列表時請分頁讀取,不要一把 Key 一把 Key 地查。