介面概述
令牌管理介面讓你用程式完成 API Key 的全生命週期管理,不必逐個在控制台點選。 最常見的場景是批次發放:給團隊成員、給下游客戶、給不同專案各發一把 Key, 並分別限制能花多少錢、能用哪些模型、用到什麼時候。 配合定時任務,還能做到每把 Key 每天限額、次日自動恢復。額度限制
remain_quota 設定這把 Key 最多能消費多少模型限制
models 設定白名單,呼叫名單外的模型直接被拒有效期限制
expired_time 設定到期時間,到點自動失效只需要建一兩把 Key 的話,直接用控制台更快,見 如何建立 KEY。
本介面面向需要自動化發放、定期輪換、或把 Key 管理接入自有系統的場景。
如何獲取個人訪問令牌
令牌管理介面用個人訪問令牌認證(nap_ 開頭),與 API Key 不是一回事。
1
打開個人訪問令牌
訪問
api.apiyi.com/account/profile 個人中心,在「賬戶選項」裡點選 個人訪問令牌 → 建立令牌2
按用途勾選「模型金鑰」權限
三項權限相互獨立,只勾用得到的:
批次發 Key 的指令碼三項都要勾;只做用量巡檢的指令碼勾「讀取」即可。
3
設定到期時間與 IP 白名單
到期時間預設 30 天,建議選久一點。發 Key 的指令碼跑在固定 IP 的伺服器上時,強烈建議設定 IP 白名單(建立後不能修改,可以先不填調通,再新建一把帶白名單的正式令牌)

端點一覽
所有端點的認證方式相同:Authorization 請求頭填個人訪問令牌,Bearer 字首可加可不加。
基礎地址為
https://api.apiyi.com。
建立令牌
請求示例
請求欄位
響應示例
獲取 Key 明文
- 需要個人訪問令牌勾選 模型金鑰 · 檢視金鑰,否則返回 403
ACCESS_TOKEN_SCOPE_DENIED - 返回的
key不含sk-字首,實際使用時需要自己拼上,即上例中真正的 API Key 是sk-K1RPzapu… - 拿到後立即儲存並通過安全渠道分發,不要把響應體留在日誌檔案裡
批次建立
服務端沒有批次建立介面 —— 在請求體裡傳count 之類的引數不會生效,仍然只建立一把。
批次發放的做法是在客戶端迴圈呼叫建立介面。
- Python
- Node.js
- cURL
三重限制怎麼用
額度限制
remain_quota 是這把令牌能消費的額度上限,換算關係與餘額查詢 一致:
換算規則
500,000 額度 = $1.00 美金 (USD)
remain_quota: 5000000 且
unlimited_quota: false。用量可以從令牌的 used_quota 欄位讀取。
remain_quota 是一次性的總額度,用完不會自動恢復。要「每天限額」,見下文場景:每把 Key 每天限額,次日自動恢復。
模型限制
models 是逗號分隔的白名單。設定後,用這把 Key 呼叫名單外的模型會被直接拒絕:
models 表示不限制。
有效期限制
expired_time 是 Unix 秒時間戳,-1 表示永不過期。例如發一把 30 天后失效的 Key:
查詢令牌
更新令牌
場景:每把 Key 每天限額,次日自動恢復
企業把 Key 發給工作流、成員或下游專案時,常見的訴求是「每把 Key 每天最多花 $5,第二天自動恢復」, 這樣某個工作流跑飛了,損失也只限於一天的額度。 平臺目前沒有內建「每日額度」欄位,但用上面的更新介面加一個每天零點跑一次的定時任務就能做到: 每天把這幾把 Key 的remain_quota 改回當日上限。Key 本身不變,團隊成員不用換 Key,
當天額度用完後呼叫會被拒絕(不扣費),零點重置後自動恢復。
1
準備個人訪問令牌
勾選 模型金鑰 · 讀取 和 模型金鑰 · 寫入 即可,不需要「檢視金鑰」。
指令碼跑在固定 IP 的伺服器上時,建議給這把令牌設定 IP 白名單。
2
列出要限額的 Key 及每日上限
用「查詢令牌」介面查到各 Key 的
id,填進下面指令碼的 DAILY_BUDGET_USD。3
每天 00:00 (UTC+8) 執行一次指令碼
用 cron、雲函式定時觸發器或任意排程器都可以,見下文。
重置指令碼
- 防重複:同一天內重複觸發(排程器補跑、手動重跑)不會再發一次額度
- 結轉超支:額度是軟上限(見下方說明),昨天超出的部分從今天扣回,長期看每天平均不超過上限;
不需要的話把
CARRY_OVERDRAFT改成False - 輸出昨日花費:每次執行列印各 Key 上一週期花了多少,日誌留著就是一份簡易日報
定時執行
把令牌寫進只有自己可讀的環境變數檔案,再用 cron 每天觸發:TZ。
使用前要知道的幾點
- 重置是覆蓋,不是累加:沒用完的額度不會滾到第二天。另外,在控制台手動改了這些 Key 的額度,下次重置時會被覆蓋
- 零點前後的在途請求:零點前發出、零點後才結束的請求,費用可能記進新的一天,金額一般很小
- 指令碼沒跑時 Key 會停在用完狀態:結果是暫時不能呼叫,不會多花錢。建議給定時任務加失敗告警
- 賬戶餘額仍是總閘:各 Key 的每日額度加起來超過賬戶餘額時,餘額先耗盡,所有 Key 都會停
- 單個 Key 想臨時多給點:直接用更新介面把它當天的
remain_quota調高,次日照常重置回上限
停用與刪除
停用(保留記錄)
停用後該 Key 立即失效,再用它呼叫模型會返回 401,但令牌記錄和歷史用量仍然保留。刪除(不可恢復)
刪除是不可恢復操作。如果只是想臨時停用,用上面的停用方式,歷史用量記錄會保留下來便於對賬。
常見問題
建立時返回的 key 怎麼直接不能用?
建立時返回的 key 怎麼直接不能用?
建立介面返回的
key 是打碼後的值(中間是一串 *),不能直接用。用返回的 id 調
POST /api/token/{id}/key 取明文(需勾「檢視金鑰」權限),再在前面拼上 sk-。
早期指令碼若直接用建立響應裡的 key,換成個人訪問令牌時需要補上這一步。為什麼我建出來的令牌一呼叫就提示額度不足?
為什麼我建出來的令牌一呼叫就提示額度不足?
最可能的原因是建立時既沒傳
remain_quota,也沒把 unlimited_quota 設為 true ——
兩者的預設組合會建出一把額度為 0 的令牌。重新建立時顯式指定其中之一即可。傳了 model_limits 或 allow_ips 為什麼沒有效果?
傳了 model_limits 或 allow_ips 為什麼沒有效果?
這兩個欄位(以及
model_limits_enabled)當前不生效,傳入不會報錯但也不會落庫。
限制可用模型請使用 models 欄位;限制來源 IP 目前需要在你自己的服務側實現。能一次建立多把令牌嗎?
能一次建立多把令牌嗎?
服務端沒有批次建立介面,在請求體裡傳
count 之類的引數不會生效。
批次發放請在客戶端迴圈呼叫建立介面,參考上面「批次建立」一節的示例。一個賬號最多能有多少把令牌?
一個賬號最多能有多少把令牌?
單個使用者最多 1000 個令牌,已停用但未刪除的也計入這個總量。達到上限後建立介面會失敗,
需要先刪除不再使用的令牌。輪換 Key 時記得走到「刪除」這一步,只停用不刪除會佔著名額。
能不能限制每把 Key 每天的花費,第二天自動恢復?
能不能限制每把 Key 每天的花費,第二天自動恢復?
平臺沒有內建「每日額度」欄位,但可以用定時任務實現:每天 00:00 (UTC+8) 調更新介面,
把這些 Key 的
remain_quota 改回當日上限。Key 不用換,當天用完會被拒絕且不扣費,次日自動恢復。
完整指令碼與注意事項見上文場景:每把 Key 每天限額,次日自動恢復。更新令牌後其他欄位被清空了?
更新令牌後其他欄位被清空了?
更新介面需要傳完整物件。先
GET 拿到完整物件,改完再整個 PUT 回去,
不要只傳要改的那幾個欄位。停用和刪除有什麼區別?
停用和刪除有什麼區別?
停用(
status: 2)後 Key 立即失效,但令牌記錄與歷史用量保留,可以隨時改回 1 恢復。
刪除是不可恢復的,記錄一併移除。臨時停用建議用停用。怎麼知道每把 Key 各自花了多少錢?
怎麼知道每把 Key 各自花了多少錢?
令牌物件的
used_quota 欄位就是這把 Key 的累計消費(÷ 500,000 = 美元)。
需要按時間段拆分或看每次呼叫的明細,去控制台日誌頁按令牌名篩選,
見如何檢視我的呼叫記錄。注意事項
操作建議
- 批次建立時建議在迴圈里加適度間隔,避免瞬時併發過高
- 給每把 Key 起有意義的
name(如team-alice、prod-webhook),便於後續在日誌裡按token_name歸因 - 定期輪換:新建 Key → 切流量 → 停用舊 Key 觀察一段時間 → 確認無呼叫後再刪除
相關文件
- 如何檢視我的呼叫記錄 —— 在控制台查每把 Key 的呼叫明細與扣費
- 餘額查詢 API —— 查賬號剩餘額度
- 如何建立 KEY —— 控制台手動建立
- 令牌與分組 —— 分組的作用與選擇