# 驗證

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

## API 金鑰

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

```bash
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"
```

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

> [!WARNING]
> 請將金鑰保存在伺服器上：任何擁有金鑰的人都可以使用該金鑰獲准使用的 API 點數。如果金鑰外洩，請撤銷它並建立新的金鑰。

不帶金鑰的請求會收到代碼為 `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` 拒絕，且不會收費。

> [!IMPORTANT]
> 預算拒絕是最終結果：在擁有者提高預算前，重試不會有幫助。

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

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

```json 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`；等其中一個完成後再重新啟動。