> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiid.edu.kg/llms.txt
> Use this file to discover all available pages before exploring further.

# 呼び出し規約

> 認証、エラー構造、共通列挙型、および非同期タスク照会に関する説明。

## 認証方法

すべての公開 API は、デフォルトで Bearer Token を使用します：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

ベース URL：

```text theme={null}
https://api.aiid.edu.kg
```

一部のネイティブ形式またはモデル専用インターフェースはパスが異なりますが、API Key の認証方式は同じです。

## エラー構造

失敗したリクエストを調査する際は、以下を優先的に確認してください：

* HTTP ステータスコード
* `error.code`
* `error.message`

代表的な構造：

```json theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "the reason why error occurred"
  }
}
```

## 主なステータスコード

| HTTP | 意味              | 推奨                                 |
| ---- | --------------- | ---------------------------------- |
| 400  | リクエストパラメータエラー   | 必須フィールド、モデル名、パスパラメータを確認してください      |
| 401  | 認証に失敗しました       | API Key が有効か確認してください               |
| 404  | パスまたはタスクが存在しません | クエリパスとタスク ID を確認してください             |
| 429  | レート制限に到達        | リクエスト頻度を下げるか、再試行してください             |
| 500  | サーバーエラー         | リクエストを記録した上で再試行するか、サポートにお問い合わせください |

## 一般的なステータス列挙値

一般的なロール (Role) 列挙値：

* `system`
* `user`
* `assistant`

一般的な長時間タスクのステータス：

* `queued`
* `running`
* `succeeded`
* `failed`
* `in_progress`
* `completed`

ビデオ API によって返されるステータスフィールドは若干異なる場合がありますが、意味は「待機中 / 実行中 / 完了 / 失敗」を基本としています。

## 非同期タスクのクエリ

現在の公開ドキュメントは「タスク結果の能動的なクエリ」を主体としており、主な方法には以下が含まれます：

* `GET /v1/videos/{task_id}`
* `GET /v1/responses/{response_id}`
* `GET /api/v3/contents/generations/tasks/{task_id}`
* `GET /suno/fetch/{task_id}`
* `GET /ent/v2/tasks/{task_id}/creations`
* `GET /v1beta/{operation_name}`

実装側への推奨事項：

* タスククエリに対して再試行とエクスポネンシャルバックオフを実施する
* `task_id` または `operation_name` を永続化して保存する
* 結果照会は、非同期タスクのポーリング（回查）におけるフォールバック手段として利用します