文件

文件

Key 分組

為每個客戶發各自的 API Key,把它們放進一個分組,隨時讀出任一時段裡每個客戶、每把 Key 花了多少,並限制每個客戶一個月最多能花多少。一個帳戶,一個餘額。

分組是帳戶裡的一個 API Key 資料夾,例如每個客戶一個:CID000001、CID000002。組裡的 Key 呼叫 API 和其他 Key 完全一樣,分組也沒有自己的餘額、儲值或登入;分組可以設一個月度上限,按組內全部 Key 合計。一把 Key 屬於一個分組,或不屬於任何分組。

三步建好分組

  • 建立分組。在API 金鑰頁面點「新增分組」,用客戶名稱命名。
  • 把 Key 放進去。點分組標題上的「新增 Key」,直接在組裡建立 Key。已有的 Key 請開啟它的選單,選「移到分組」。
  • 讀數。API 金鑰頁面顯示每把 Key 本日曆月的花費和每個分組的合計。用量頁面把同樣的 Key 按分組列出,可選今日、近 7 天、近 30 天、本月、上月,或自選日期(最長 90 天)。

讀出一個月並匯出

在用量頁面頂端選「上月」(或「本月」,或用「自訂」選日期)。在「按 API Key」裡,每個分組的標題列顯示它的花費和呼叫次數。頁面頂端的分組選單可以把整頁縮小到一個分組:它的數字、曲線、模型和呼叫紀錄。「匯出 CSV」下載的就是頁面目前顯示的內容:同一個時間範圍、同一個分組,可按 Key 彙總,也可按天。

按 Key 彙總時,檔案每把 Key 在每個分組下一列,檔名形如 kunavo-cost-by-key_2026-10-01_2026-10-31.csv。它列出時間範圍內有呼叫的每把 Key(含已撤銷的),放在每次呼叫發生時所在的分組下;以及在目前所在分組裡沒有呼叫的每把可用 Key(記為 0),所以每個客戶的 Key 名單是完整的。分組按控制台裡的順序排列,組內的 Key 按花費從高到低,未分組的 Key 排在最後。按天匯出時,檔案第一欄是 date,每把 Key 在某個分組裡有呼叫的每一天一列。

欄位內容
group呼叫發生時所在的分組;不屬於任何分組的呼叫為空。之後被刪除的分組,名稱後面帶 (deleted)。
key_nameKey 的名稱。
key_prefixKey 的開頭部分,和控制台裡顯示的一樣。不會是完整的 Key。
key_statusactive 或 revoked。
calls這把 Key 在時間範圍內的呼叫次數。
errors其中失敗的呼叫次數。失敗的呼叫不收費。
input_tokens輸入 token 數,含快取讀取和快取寫入。
output_tokens輸出 token 數。
cached_input_tokens輸入 token 中從提示快取讀取的部分。
cache_write_tokens輸入 token 中寫入提示快取的部分。
cost_usd這些呼叫的扣款金額,單位美元,保留八位小數。
看起來像公式的名稱。以 =、+、- 或 @ 開頭的分組名稱或 Key 名稱,匯出時前面會加一個單引號,這樣試算表會把它當作文字顯示,而不是當作公式執行。

限制每個分組一個月的花費

在 API 金鑰頁面開啟分組的選單,選「設定月度上限」。這個上限按分組內全部 Key 在一個日曆月(UTC)裡的合計花費計算,也就是每把 Key 在該分組期間產生的呼叫。會讓分組超過上限的請求會以 402 遭拒,且不收取任何費用。留空表示不限;填 0 可以在不撤銷任何 Key 的前提下暫停組裡的所有 Key。

每把 Key 自己的月度上限照常生效,先達到哪個,就由哪個拒絕請求。分組標題顯示本月花費對上限的進度;請求開始遭拒後顯示「已達上限」,上限為 0 時顯示「已暫停」。

當一個分組,或設了自身上限的一把 Key,本月用到上限的 80% 時,Kunavo 會寄一封信到你的帳戶信箱;請求開始因這個上限遭拒時再寄一封。每個上限每種信每月最多一封。

數字怎麼算

  • 花費就是扣款金額。每次呼叫的花費,是它完成時從你的餘額扣除的金額。失敗的呼叫不收費。
  • 月和日都按 UTC。本月從 1 日 00:00 UTC 開始。例如在仰光(UTC+6:30),10 月在當地時間 11 月 1 日 06:30 結束。用量頁面會寫出目前範圍涵蓋的日期。
  • 呼叫算在發生時 Key 所在的分組。把一把 Key 移到另一個分組,只有從那之後的呼叫算在新分組;它先前的呼叫留在原處。所以 API 金鑰頁面上一個分組的本月合計,可能不等於它下面現在列出的各把 Key 之和。
  • 已撤銷的 Key 留在原分組。它在撤銷前的花費仍計入該分組的合計,也會出現在匯出檔案裡。
  • 刪除的分組保留它的呼叫。這些呼叫在用量頁面和匯出檔案裡仍顯示在它的名稱下,並標示已刪除;這個名稱也可以再用來建立新分組。
  • 三處數字一致。同一個自然月,一個分組在 API 金鑰頁面的合計、在用量頁面「本月」下的合計,以及 CSV 裡該組各列之和,三者完全相同,精確到分。

常見問題

  • 每個分組有自己的餘額嗎?沒有。所有分組共用帳戶的同一個餘額。要限制某個客戶的花費,請為它的分組設定月度上限,或為它的每把 Key 設定月度上限。
  • 我的客戶能登入查看用量嗎?不能。分組只有你自己看得到。每把 Key 可以用 GET /v1/usage 查詢自己的用量,回傳結果裡不包含分組。如果它的分組設了月度上限,GET /v1/balance 會告訴這把 Key 這個上限和整個分組本月已花的金額,但不包含分組的名稱。
  • 刪除分組會怎樣?由你選擇:組裡的 Key 繼續可用,從此不屬於任何分組;或者隨分組一起撤銷。無論哪種,它們已產生的呼叫都留在這個分組的名稱下。
  • 一把 Key 從一個客戶轉給另一個客戶怎麼辦?把它移到另一個客戶的分組:從那之後的呼叫算在新分組,先前的呼叫留在第一個客戶名下。
  • 能查看其他時間範圍嗎?可以:在用量頁面選「自訂」,最多選 90 天。程式裡可以用 GET /v1/usage 按天查詢單把 Key 在同一時段的花費。

如果想用自己的工具而不是手動來建立、分組、限額和撤銷客戶的 Key,請使用管理 API。它的 Key 是一種獨立的憑證,只能用於該 API。