快速入門
身份驗證
使用 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
- 登入 TokenLab Console
- 開啟 API Keys
- 建立一個新的 key
- 為其命名以便識別
- 請立即複製,因為它只會顯示一次
- 切勿在客戶端程式碼中暴露 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- 開頭。
錯誤回應
| 狀態碼 | 類型 | 代碼 | 說明 |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | API key 缺失、無效、未啟用或已撤銷 |
| 401 | expired_api_key | expired_api_key | Key 已過期 |
| 402 | insufficient_balance | insufficient_balance | 帳戶餘額不足 |
| 402 | quota_exceeded | quota_exceeded | 已達到 API key 使用限額 |
| 403 | permission_error | model_not_allowed | 該 key 不被允許使用所請求的模型 |
| 403 | permission_error | user_suspended, account_restricted | 帳戶無法使用 API |
| 429 | rate_limit_exceeded | rate_limit_exceeded | 來自單一 IP 位址的身份驗證失敗次數過多。請等待 Retry-After 並修正 key;請勿在 401 錯誤時進行迴圈請求 |
範例:
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}