跳至內容
中文 (繁體)
取得 API 金鑰
API 指南

驗證

以 Markdown 檢視 已更新

每個執行模型或讀取請求的呼叫都需要 API 金鑰。目錄（GET /models、GET /categories）、POST /quote 和 OpenAPI 文件都是公開的。

API 金鑰

在 https://doitong.com/developers/dashboard#keys 建立和撤銷金鑰。金鑰的格式為 doitong_ 後接 64 個十六進位字元，且只會在建立時顯示一次。將它放入 Authorization 標頭中傳送：

終端機
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"

X-API-Key: <key> 也可以使用。

不帶金鑰的請求會收到代碼為 missing_api_key 的 401；未知、已撤銷或已過期的金鑰同樣會收到 401。

權限範圍

每個金鑰都帶有權限範圍。模型 API 會檢查以下範圍：

動作 所需範圍
執行模型、取消請求、刪除請求的檔案、變更儲存空間設定 models:run（具有較舊 images:create 或 videos:create 的金鑰也可使用）
建立上傳 URL models:run 或 media:upload
讀取請求、帳戶 models:read（可執行模型的金鑰也可讀取）

新金鑰預設值為 models:read 和 models:run。缺少正確權限範圍的呼叫會收到代碼為 insufficient_scope 的 403。

點數預算

金鑰可以有自己的 API 點數預算（1,000 API 點數 = $1），由帳戶擁有者設定：總預算、每日預算（最近 24 小時），或兩者皆有。執行收費前，系統會將費用與該金鑰透過此 API 已花費的金額（扣除退款後）進行比對。超出預算的執行會以 402 budget_exceeded 拒絕，且不會收費。

沒有預算的金鑰最多可以使用 API 餘額。除此之外，如果 API 餘額不足以支付執行費用，會收到 402 insufficient_credits 和 top_up_url。

GET https://api.doitong.com/v1/account 會顯示 API 餘額及金鑰剩餘的預算（兩者皆以 API 點數表示）：

200 OK · 帳戶
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}

當金鑰沒有自己的預算時，budget_remaining 為 null。

速率限制

每個金鑰每小時最多可提出 3600 個請求，除非其限制另有設定。每個經過驗證的回應都會包含目前狀態：

標頭 意義
X-RateLimit-Limit 目前時間窗內允許的請求數
X-RateLimit-Remaining 目前時間窗內剩餘的請求數
X-RateLimit-Reset 時間窗重設的 Unix 時間

超過限制時會收到帶有 Retry-After 標頭的 429（秒）。使用 ?wait= 的長輪詢每次呼叫計為一個請求，因此等待比快速輪詢更節省。

每個帳戶同時還限制最多 10 個處理中的請求（queued 或 running）。再啟動一個請求會回傳 429 too_many_inflight；等其中一個完成後再重新啟動。