# 認証

モデルを実行する、またはリクエストを読み取るすべての呼び出しにはAPIキーが必要です。カタログ（`GET /models`、`GET /categories`）、`POST /quote`、OpenAPIドキュメントは公開されています。

## APIキー

[https://doitong.com/developers/dashboard#keys](https://doitong.com/developers/dashboard#keys) でキーを作成および無効化できます。キーは `doitong_` に続く64個の16進文字で構成され、作成時に一度だけ表示されます。`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残高で支払えない実行には `top_up_url` とともに `402 insufficient_credits` が返されます。

`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` になります。

## レート制限

各キーは、別の制限が設定されていない限り、1時間あたり3600件のリクエストを実行できます。認証済みのすべてのレスポンスには現在の状態が含まれます。

| ヘッダー | 意味 |
|---|---|
| `X-RateLimit-Limit` | 現在のウィンドウで許可されるリクエスト数 |
| `X-RateLimit-Remaining` | 現在のウィンドウで残っているリクエスト数 |
| `X-RateLimit-Reset` | ウィンドウがリセットされるUnix時刻 |

制限を超えると、`Retry-After` ヘッダー（秒）とともに `429` が返されます。`?wait=` を使用した長時間のポーリングは、呼び出しごとに1件のリクエストとして数えられるため、短い間隔でポーリングするより待機するほうが効率的です。

また、1アカウントあたり同時に進行できるリクエスト（`queued` または `running`）は10件までです。もう1件開始しようとすると `429 too_many_inflight` が返されるため、いずれかが完了してから再度開始してください。