跳轉到主要內容

介面概述

令牌管理介面讓你用程式完成 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 白名單(建立後不能修改,可以先不填調通,再新建一把帶白名單的正式令牌)
建立個人訪問令牌:名稱、到期時間、IP 白名單與權限
勾了「寫入」和「檢視金鑰」的令牌能創建出可以呼叫模型的 API Key,請像保管賬號密碼一樣保管它。個人訪問令牌本身不能呼叫模型,但它能發出可以呼叫模型的 Key。因此這類令牌務必設定 IP 白名單、 存進金鑰管理工具而不是寫在程式碼裡,不要提交進程式碼倉庫,並在到期前及時換新。
舊系統令牌計劃於 2026-11-11 (UTC+8) 停用。 原來在「賬號選項 - 系統令牌」生成的 AccessToken 在此之前照常可用,之後會返回 401 ACCESS_TOKEN_LEGACY_RETIRED。 平臺會視使用情況決定是否延期,建議儘早換成個人訪問令牌。換令牌時請同時檢查指令碼:新版建立介面返回的 key 已打碼,取明文要另調一次 POST /api/token/{id}/key,見下文。 詳見 什麼是個人訪問令牌?

端點一覽

所有端點的認證方式相同:Authorization 請求頭填個人訪問令牌,Bearer 字首可加可不加。 基礎地址為 https://api.apiyi.com。

建立令牌

請求示例

請求欄位

unlimited_quota 預設為 false,而 remain_quota 預設為 0 —— 兩者一起預設時會建出一把 額度為 0、無法使用的令牌。要麼顯式給 remain_quota 賦值,要麼把 unlimited_quota 設為 true。
模型白名單請使用 models 欄位。響應結構裡還存在 model_limits、model_limits_enabled、allow_ips 三個欄位, 傳入它們不會報錯(介面仍返回 200),但當前不會生效 —— 回讀時這些欄位仍為空。 需要限制可用模型請使用 models,需要限制來源 IP 請在自己的服務側實現。

響應示例

響應裡的 key 是打碼後的值,不能直接使用。 要拿到明文,用響應裡的 id 再調一次獲取明文介面。

獲取 Key 明文

  • 需要個人訪問令牌勾選 模型金鑰 · 檢視金鑰,否則返回 403 ACCESS_TOKEN_SCOPE_DENIED
  • 返回的 key 不含 sk- 字首,實際使用時需要自己拼上,即上例中真正的 API Key 是 sk-K1RPzapu…
  • 拿到後立即儲存並通過安全渠道分發,不要把響應體留在日誌檔案裡

批次建立

服務端沒有批次建立介面 —— 在請求體裡傳 count 之類的引數不會生效,仍然只建立一把。 批次發放的做法是在客戶端迴圈呼叫建立介面。
單個使用者最多 1000 個令牌。 這是賬號級別的總量上限,包含已停用但未刪除的令牌。 達到上限後建立介面會失敗,需要先刪除不再使用的令牌騰出名額。批次發放前先用 GET /api/token/?p=0&page_size=100 翻頁統計當前數量, 把「新建 Key → 切流量 → 停用舊 Key → 確認無呼叫後刪除」中的最後一步真正執行到位, 不要只停用不刪除,否則輪換幾輪就會撞到上限。

三重限制怎麼用

額度限制

remain_quota 是這把令牌能消費的額度上限,換算關係與餘額查詢 一致:

換算規則

500,000 額度 = $1.00 美金 (USD)
例如給下游客戶發一把最多消費 $10 的 Key,就設 remain_quota: 5000000 且 unlimited_quota: false。用量可以從令牌的 used_quota 欄位讀取。 remain_quota 是一次性的總額度,用完不會自動恢復。要「每天限額」,見下文場景:每把 Key 每天限額,次日自動恢復。

模型限制

models 是逗號分隔的白名單。設定後,用這把 Key 呼叫名單外的模型會被直接拒絕:
返回 HTTP 403,不產生扣費。不傳 models 表示不限制。

有效期限制

expired_time 是 Unix 秒時間戳,-1 表示永不過期。例如發一把 30 天后失效的 Key:

查詢令牌

關鍵欄位:

更新令牌

更新介面需要傳完整物件,不是增量更新(patch)。正確做法是:先 GET 拿到令牌的完整物件 → 修改需要變更的欄位 → 把整個物件 PUT 回去。 只傳要改的那幾個欄位會把其餘欄位清空。

場景:每把 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 每天觸發:
想按別的時區劃分「一天」,同時改 cron 時間和腳本里的 TZ。

使用前要知道的幾點

額度是軟上限,不是精確的剎車。 額度檢查發生在請求開始時,幾個併發請求可能同時通過檢查, 單次很貴的請求(影片、4K 出圖、超長上下文)也可能一次就越過上限,餘額會被打成負數。 併發越高、單價越高,超出越多。指令碼的「結轉超支」會把超出部分從次日扣回; 如果某些 Key 不能有任何超支,就在自己的服務側控制它的併發數,或者用 models 白名單把高單價模型排除在外。
  • 重置是覆蓋,不是累加:沒用完的額度不會滾到第二天。另外,在控制台手動改了這些 Key 的額度,下次重置時會被覆蓋
  • 零點前後的在途請求:零點前發出、零點後才結束的請求,費用可能記進新的一天,金額一般很小
  • 指令碼沒跑時 Key 會停在用完狀態:結果是暫時不能呼叫,不會多花錢。建議給定時任務加失敗告警
  • 賬戶餘額仍是總閘:各 Key 的每日額度加起來超過賬戶餘額時,餘額先耗盡,所有 Key 都會停
  • 單個 Key 想臨時多給點:直接用更新介面把它當天的 remain_quota 調高,次日照常重置回上限

停用與刪除

停用(保留記錄)

停用後該 Key 立即失效,再用它呼叫模型會返回 401,但令牌記錄和歷史用量仍然保留。

刪除(不可恢復)

批次刪除同樣在客戶端迴圈即可:
刪除是不可恢復操作。如果只是想臨時停用,用上面的停用方式,歷史用量記錄會保留下來便於對賬。

常見問題

建立介面返回的 key 是打碼後的值(中間是一串 *),不能直接用。用返回的 id 調 POST /api/token/{id}/key 取明文(需勾「檢視金鑰」權限),再在前面拼上 sk-。 早期指令碼若直接用建立響應裡的 key,換成個人訪問令牌時需要補上這一步。
最可能的原因是建立時既沒傳 remain_quota,也沒把 unlimited_quota 設為 true —— 兩者的預設組合會建出一把額度為 0 的令牌。重新建立時顯式指定其中之一即可。
這兩個欄位(以及 model_limits_enabled)當前不生效,傳入不會報錯但也不會落庫。 限制可用模型請使用 models 欄位;限制來源 IP 目前需要在你自己的服務側實現。
服務端沒有批次建立介面,在請求體裡傳 count 之類的引數不會生效。 批次發放請在客戶端迴圈呼叫建立介面,參考上面「批次建立」一節的示例。
單個使用者最多 1000 個令牌,已停用但未刪除的也計入這個總量。達到上限後建立介面會失敗, 需要先刪除不再使用的令牌。輪換 Key 時記得走到「刪除」這一步,只停用不刪除會佔著名額。
平臺沒有內建「每日額度」欄位,但可以用定時任務實現:每天 00:00 (UTC+8) 調更新介面, 把這些 Key 的 remain_quota 改回當日上限。Key 不用換,當天用完會被拒絕且不扣費,次日自動恢復。 完整指令碼與注意事項見上文場景:每把 Key 每天限額,次日自動恢復。
更新介面需要傳完整物件。先 GET 拿到完整物件,改完再整個 PUT 回去, 不要只傳要改的那幾個欄位。
停用(status: 2)後 Key 立即失效,但令牌記錄與歷史用量保留,可以隨時改回 1 恢復。 刪除是不可恢復的,記錄一併移除。臨時停用建議用停用。
令牌物件的 used_quota 欄位就是這把 Key 的累計消費(÷ 500,000 = 美元)。 需要按時間段拆分或看每次呼叫的明細,去控制台日誌頁按令牌名篩選, 見如何檢視我的呼叫記錄。

注意事項

個人訪問令牌不是 API Key,兩者不能互換
  • API Key(sk- 開頭)用於 /v1/* 推理端點
  • 個人訪問令牌(nap_ 開頭)用於 /api/* 管理端點,不能呼叫模型
報錯對照:401 ACCESS_TOKEN_LEGACY_RETIRED 是仍在用已停用的舊系統令牌; 401 This access token may not be used from the current IP address. 是來源 IP 不在令牌白名單內; 403 ACCESS_TOKEN_SCOPE_DENIED 是令牌沒勾這個介面需要的權限(見上方端點一覽)。
妥善保管明文 Key「獲取 Key 明文」介面返回的是可以直接呼叫模型的 Key。請注意:
  • 不要把包含 key 的原始響應寫進日誌檔案或提交進程式碼倉庫
  • 分發給團隊成員時使用安全渠道,不要通過聊天群直接傳送
  • 這段明文不帶 sk- 字首,常見的金鑰掃描工具可能掃不出來,不要依賴自動化檢查兜底
操作建議
  • 批次建立時建議在迴圈里加適度間隔,避免瞬時併發過高
  • 給每把 Key 起有意義的 name(如 team-alice、prod-webhook),便於後續在日誌裡按 token_name 歸因
  • 定期輪換:新建 Key → 切流量 → 停用舊 Key 觀察一段時間 → 確認無呼叫後再刪除

相關文件