TokenLab

快速入門

身份驗證

使用 API key 對 TokenLab API 請求進行身份驗證

API Keys

模型呼叫與私有資源需要 API key。公開的探索端點(例如 GET /v1/models 和 GET /v1/models/{model})無需 API key 即可運作。成功的探索回應並不代表您的 key 可正常運作;請遵循「快速入門」(Quickstart) 來發送模型請求。請使用完整的已儲存 key;key 列表中的前綴無法用於身份驗證。

對於與 OpenAI 相容的端點,請按以下方式發送:

Authorization: Bearer sk-your-api-key

對於與 Anthropic 相容的 /v1/messages 請求,您也可以使用:

x-api-key: sk-your-api-key

與 Gemini 相容的 /v1beta/* 請求也接受 x-goog-api-key: sk-your-api-key。建議優先使用標頭 (header) 而非 ?key= 查詢參數,因為 URL 常會被記錄在日誌中。

Management Tokens

Management API 端點使用另一種 token 類型:

Authorization: Bearer mt-your-management-token

請僅將 management tokens 用於 /v1/management/* 端點。開啟所選工作區的 API → Tokens 以建立或替換 token。請在顯示時儲存完整的 token;它僅在建立或替換後顯示一次。

Management tokens 不能用於模型推論,標準的 sk-... API keys 也不能用於 Management API。

取得 API key

  1. 登入 TokenLab Console
  2. 開啟 API Keys
  3. 建立一個新的 key
  4. 為其命名以便識別
  5. 請立即複製,因為它只會顯示一次
  • 切勿在客戶端程式碼中暴露 API keys
  • 切勿將 API keys 提交至版本控制系統
  • 請使用環境變數或密鑰管理服務 (secret manager)
  • 定期輪替 (rotate) keys
  • 刪除未使用的 keys

使用 API key

請參閱 快速入門 以了解環境變數與第一個完整請求。請使用與您選擇的 API 格式 相符的 SDK;並將 keys 保留在伺服器端。

Key 設定

您可以在 Console 中針對每個 API key 進行設定,也可以透過 管理 API 進行設定:

設定說明
消費限額 (Spending limit)No limit 允許該 key 使用工作區餘額。Fixed limit 會在達到設定金額後使該 key 回傳 402 quota_exceeded。
允許的模型 (Allowed models)該 key 僅能呼叫這些模型。其他模型會回傳 403 model_not_allowed。留空則表示無 key 層級的限制。
交付選項 (Delivery option)針對此 key 的請求設定 Auto、Verified 或 Official。留空則使用工作區預設值。請參閱 帳務與定價。
過期時間 (Expiration)超過此時間後,該 key 將回傳 401 expired_api_key。
狀態 (Status)inactive(已暫停)的 key 會回傳 401 invalid_api_key。revoked(已撤銷)的 key 無法再次啟用。

Key 前綴

所有 TokenLab API keys 皆以 sk- 開頭。

錯誤回應

狀態碼類型代碼說明
401invalid_api_keyinvalid_api_keyAPI key 缺失、無效、未啟用或已撤銷
401expired_api_keyexpired_api_keyKey 已過期
402insufficient_balanceinsufficient_balance帳戶餘額不足
402quota_exceededquota_exceeded已達到 API key 使用限額
403permission_errormodel_not_allowed該 key 不被允許使用所請求的模型
403permission_erroruser_suspended, account_restricted帳戶無法使用 API
429rate_limit_exceededrate_limit_exceeded來自單一 IP 位址的身份驗證失敗次數過多。請等待 Retry-After 並修正 key;請勿在 401 錯誤時進行迴圈請求

範例:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

本頁內容