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

# 非同期タスク

> AIHubMix 非同期タスク API：画像は async 指定、動画は既定で非同期、LLM 中断リカバリーは最終レスポンスを保存。/ai/v1/tasks でステータス照会、結果ダウンロード、Webhook 受信に対応します。

動画生成やバッチ画像生成のようなリクエストは、1 回の HTTP 接続で待てる時間を超えることが一般的です。また、長文生成の途中でクライアントが切断すると、すでに生成された部分のレスポンスも取り戻せません。

**非同期タスク**（Async Tasks）は、この 3 つのシナリオを同一のタスクオブジェクトに統一します。画像と動画は生成 API でタスクを作成して `task_id` を即時に返し、クライアントが中断した LLM リクエストはプラットフォーム側が処理を継続して最終レスポンスを保存します。3 種類とも同じタスクステータス、照会 API、結果ダウンロードのフローを共有します。

<Note>
  タスクの照会と結果のダウンロードには、タスク作成時と同じ API Key を使用してください。タスクは API Key 単位で分離されており、2 つの Key が同じアカウントに属していても相互に読み取ることはできません。
</Note>

<Card title="コンソールで非同期タスクを有効化する" icon="list-check" href="https://console.aihubmix.com/support" horizontal>
  非同期の画像または動画を作成する前に、現在のアカウントで非同期タスク機能を有効化してください。コンソールにこの入口が表示されていない場合は、AIHubMix テクニカルサポートへお問い合わせください。
</Card>

<Warning>
  非同期タスク機能が有効化されていない場合、メディアタスクの作成リクエストは `403 async_not_enabled` を返します。LLM リクエストはこれによってエラーにはなりませんが、クライアントが中断した後に最終レスポンスを取り戻すことはできません。
</Warning>

***

<h2 id="quickstart">
  クイックスタート
</h2>

画像と動画の非同期タスクの全体フローは 3 ステップです：

```text theme={null}
1. タスクを送信 -> task_id を取得
2. ステータスを照会 -> タスクの完了を待つ
3. 結果を取得 -> ファイルをダウンロード、またはレスポンス内容を読み取る
```

<CodeGroup>
  ```shell curl theme={null}
  # ステップ 1：非同期の動画タスクを送信
  curl -X POST https://aihubmix.com/ai/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-t2v",
      "prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
      "seconds": "5",
      "size": "1280x720"
    }'

  # ステップ 2：15 秒ごとに照会し、タスクが完了、失敗、または取消になるまで繰り返す
  curl https://aihubmix.com/ai/v1/tasks/{task_id} \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY"

  # ステップ 3：単一の成果物をダウンロード
  curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    --output result.mp4
  ```

  ```json 作成レスポンス theme={null}
  {
    "id": "task_01K0...",
    "object": "video",
    "model": "wan2.6-t2v",
    "status": "in_progress",
    "output": [],
    "error": null,
    "created_at": 1784707200,
    "completed_at": null,
    "expires_at": null
  }
  ```
</CodeGroup>

***

<h2 id="sync-vs-async">
  同期呼び出し vs 非同期タスクの比較
</h2>

| リクエスト種別    | デフォルトの返却方式      | 非同期の方式                                           |
| ---------- | --------------- | ------------------------------------------------ |
| 画像生成       | 生成結果を同期で返す      | リクエストボディに `async: true` を指定すると `task_id` を即時に返す  |
| 動画生成       | 常に非同期           | 作成後に `task_id` を返し、タスク API で結果を取得する              |
| LLM テキスト生成 | 同期またはストリーミングで返す | クライアントが中断し、かつ条件を満たす場合、最終レスポンスが `llm` タスクとして保存される |

同期呼び出しは 1 回の HTTP レスポンス内で結果を返すため、接続が切断されると結果は取り戻せません。非同期タスクは結果をプラットフォーム側に保存し、`task_id` を使って結果の有効期限まで同じ API Key で再照会とダウンロードができます。処理時間が長い生成リクエストや、中断後に最終レスポンスを取得する必要がある長文出力に適しています。

***

<h2 id="api-overview">
  インターフェース概要
</h2>

| 操作        | メソッド | パス                                           | 説明                          |
| --------- | ---- | -------------------------------------------- | --------------------------- |
| 非同期画像を作成  | POST | `/ai/v1/images/generations`                  | リクエストボディに `async: true` を追加 |
| 非同期動画を作成  | POST | `/ai/v1/videos`                              | 動画タスクはデフォルトで非同期             |
| タスク一覧を照会  | GET  | `/ai/v1/tasks`                               | 現在の API Key が作成したタスクを検索     |
| タスク詳細を照会  | GET  | `/ai/v1/tasks/{task_id}`                     | 統一されたタスクステータスと出力を照会         |
| 単一の結果を取得  | GET  | `/ai/v1/tasks/{task_id}/content`             | 単一成果物タスクまたは LLM タスク向け       |
| 指定した結果を取得 | GET  | `/ai/v1/tasks/{task_id}/content/{result_id}` | 複数成果物タスク向け                  |

Base URL：`https://aihubmix.com`、認証方式は Bearer Token です：

```bash theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
```

<Note>
  `/ai/v1/tasks` は読み取り専用の統一照会入口であり、`POST /ai/v1/tasks` は提供していません。画像と動画はそれぞれ対応する生成 API で作成します。[LLM 中断リカバリー](#llm-interruption-recovery)の条件を満たすリクエストは、クライアントが中断した後に `llm` タスクとして自動的に記録されます。
</Note>

***

<h2 id="supported-models">
  対応モデル
</h2>

非同期タスクの対応範囲はタスク種別ごとに分かれており、呼び出し時に追加パラメータは不要です。

<h3 id="supported-models-image">
  非同期画像
</h3>

| モデル              |
| ---------------- |
| `qwen-image-2.0` |

<h3 id="supported-models-video">
  非同期動画
</h3>

| モデル          |
| ------------ |
| `wan2.6-t2v` |

<h3 id="supported-models-llm">
  LLM 中断リカバリー
</h3>

| モデル              |
| ---------------- |
| `gpt-5.5-pro`    |
| `claude-fable-5` |

対応範囲は今後も拡張され、この表もあわせて更新されます。

***

<h2 id="create-async-task">
  非同期タスクを作成する方法
</h2>

<h3 id="create-async-image">
  非同期画像
</h3>

画像 API はデフォルトで同期的に返します。`async` を `true` に設定すると、API はタスクオブジェクトを即時に返し、生成処理はバックグラウンドで継続されます。

```bash theme={null}
curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'
```

`async` はブール値である必要があります。指定しない場合や `false` に設定した場合、画像 API は同期的な動作を維持します。

<h3 id="create-async-video">
  非同期動画
</h3>

動画 API は常に非同期です。作成に成功すると `pending` または `in_progress` のステータスを返します。`Prefer: wait` による同期待機への変更には対応していません。

```bash theme={null}
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "seconds": "5",
    "size": "1280x720"
  }'
```

<h3 id="common-parameters">
  共通パラメータ
</h3>

サンプル内の `model`、`prompt`、`n`、`seconds`、`size` は一般的なモデルパラメータです。各モデルが対応するフィールドと値は、対応するモデルの API ドキュメントを基準としてください。動画モデルについては[動画生成のドキュメント](/jp/api/Video-Gen)を参照できます。以下の表は、すべての非同期タスクで共通のパラメータのみを説明します。

| パラメータ                   | 型         | 必須            | 説明                                                  |
| ----------------------- | --------- | ------------- | --------------------------------------------------- |
| `async`                 | boolean   | 画像：必須、動画：指定不要 | 画像 API で `true` に設定すると非同期で実行される                     |
| `webhook_url`           | string    | いいえ           | 当該タスクの HTTPS コールバック URL、最大 512 文字                   |
| `webhook_events_filter` | string\[] | いいえ           | プッシュする最終ステータス、`completed`、`failed`、`cancelled` から選択 |

<Note>
  画像タスクで Webhook を使用できるのは `async: true` の場合のみです。`webhook_events_filter` を省略すると、AIHubMix は `completed`、`failed`、`cancelled` の 3 つの最終ステータスをプッシュします。指定する場合は `webhook_url` と併せて使用する必要があり、空や重複は指定できません。
</Note>

***

<h2 id="llm-interruption-recovery">
  LLM 中断リカバリーはどのように機能するか
</h2>

LLM 中断リカバリーは、クライアントが接続を切断した後の最終レスポンスを取得するための機能です。この機能は既存の LLM リクエスト方式をそのまま利用し、ストリーミングの挙動とレスポンス形式は変わりません。追加の作成 API を呼び出す必要はなく、事前に `task_id` が返されることもありません。

<h3 id="recovery-conditions">
  有効になる条件
</h3>

以下の条件をすべて満たす必要があります：

| 条件                    | 説明                                                       |
| --------------------- | -------------------------------------------------------- |
| アカウントで非同期タスク機能が有効     | AIHubMix コンソールで現在のアカウントに対して有効化する                         |
| 使用するモデルが中断リカバリーに対応    | [LLM 中断リカバリー](#supported-models-llm)を参照、呼び出し時に追加パラメータは不要 |
| 対応する LLM API を呼び出している | リクエストが以下に挙げるテキスト生成 API に該当する                             |
| クライアント側で中断が発生         | クライアントによるキャンセル、ネットワーク切断、または呼び出し元によるリクエスト取消               |

対応するインターフェース：

| インターフェース                                           | 説明                                          |
| -------------------------------------------------- | ------------------------------------------- |
| `POST /v1/chat/completions`                        | OpenAI Chat Completions、ストリーミングと非ストリーミングに対応 |
| `POST /v1/messages`                                | Anthropic Messages、ストリーミングと非ストリーミングに対応      |
| `POST /v1/responses`                               | OpenAI Responses API                        |
| Gemini `generateContent` / `streamGenerateContent` | Gemini ネイティブのテキスト生成 API                     |

<Note>
  呼び出し時に追加フィールドを渡す必要はありません。対応範囲は [LLM 中断リカバリー](#supported-models-llm)を参照してください。表に記載されていないモデルは、本番導入前に低コストのリクエストを 1 件使って中断リカバリーの検証を行えます。検証用のリクエストも通常どおり課金されます。いずれかの条件を満たさない場合、リクエストは通常どおり実行されますが、クライアントが中断しても `llm` タスクは生成されません。
</Note>

<h3 id="recovery-flow">
  中断後の実行フロー
</h3>

```text theme={null}
1. クライアントが通常どおり LLM リクエストを送信する
2. クライアントがレスポンス完了前に切断またはキャンセルする
3. AIHubMix はリクエストの処理を継続し、当該リクエストは通常どおり課金される
4. 最終的な JSON または SSE レスポンスが llm タイプのタスクとして保存される
5. 元の API Key でタスク一覧を照会し、保存されたレスポンスを読み取る
```

正常に完了し、クライアントへ返却に成功した LLM リクエストはタスクを作成せず、タスク一覧にも表示されません。中断したリクエストは最終レスポンスの保存が完了した後に一覧へ表示されるため、処理中は一時的に照会できない場合があります。

<h3 id="locate-interrupted-request">
  対応する中断リクエストを特定する
</h3>

LLM のレスポンスヘッダーには `X-Aihubmix-Request-Id` が返されます。クライアントはレスポンスヘッダーを受け取った時点でこの値を保存してください。中断が発生した後は、AIHubMix コンソールの非同期タスク一覧でこのリクエスト ID を使って該当タスクを検索できます。

公開されているタスク API は現時点でリクエスト ID によるフィルタリングに対応していません。リクエスト ID を保存していない場合は、リクエスト作成時と同じ API Key を使い、モデルと作成時刻で検索する方法のみとなります：

```bash theme={null}
# 直近の LLM 中断タスクを照会
curl "https://aihubmix.com/ai/v1/tasks?object=llm&model={model}&order=desc&limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# task_id を見つけたら、詳細を照会して元のレスポンスを取得
curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

<Warning>
  同一の API Key で同じモデルへ複数のリクエストを並行して送信した場合、モデルと作成時刻だけでは正確な対応付けを保証できません。確実にリカバリーする必要がある場合は `X-Aihubmix-Request-Id` を保存し、コンソールで検索してください。レスポンスヘッダーを取得できていない場合、一覧の最新タスクをそのまま当該リクエストのものと判断することは避けてください。
</Warning>

<Warning>
  LLM 中断リカバリーのタスクは現時点で Webhook を送信しません。結果はタスク一覧から照会してください。クライアントの中断によってプラットフォーム側の処理継続が止まることはなく、その呼び出しは元の LLM API のルールどおりに課金されます。
</Warning>

***

<h2 id="task-object">
  タスクオブジェクトとステータス
</h2>

すべてのタスクは統一されたレスポンス構造を使用します：

```json theme={null}
{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "result_id": "result_01K0XYZ",
      "type": "file",
      "content_type": "video/mp4",
      "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": 1784709120
}
```

| フィールド          | 型            | 説明                                    |
| -------------- | ------------ | ------------------------------------- |
| `id`           | string       | プラットフォームのタスク ID、以降のリクエストで使う `task_id` |
| `object`       | string       | タスク種別：`llm`、`image`、`video`           |
| `model`        | string       | タスク作成時に使用したモデル                        |
| `status`       | string       | 統一されたタスクステータス                         |
| `output`       | array        | 取得可能な結果、結果が生成されていない場合は空配列             |
| `error`        | object/null  | 失敗情報、通常は `code` と `message` を含む       |
| `created_at`   | integer      | 作成時刻、Unix 秒                           |
| `completed_at` | integer/null | タスクが完了、失敗、または取消になった時刻、Unix 秒          |
| `expires_at`   | integer/null | 最も早く期限切れになる結果の有効期限、Unix 秒             |

`output` 内の結果フィールド：

| フィールド          | 説明                                                   |
| -------------- | ---------------------------------------------------- |
| `index`        | 当該タスク内での結果の順番、0 から始まる                                |
| `result_id`    | 結果 ID、複数成果物タスクで指定した結果をダウンロードする際に使用                   |
| `type`         | 結果の種別、ファイルは `file`、LLM レスポンスは `response`             |
| `content_type` | 結果のファイル種別（MIME）、例：`video/mp4` または `application/json` |
| `content_url`  | 結果のダウンロード URL、アクセスにはタスク作成に使用した API Key が必要           |
| `b64_json`     | 一部の画像モデルが直接返す場合がある Base64 エンコードの結果                   |
| `truncated`    | LLM レスポンスがサイズ制限により切り捨てられたかどうか                        |

<h3 id="task-status">
  ステータスの説明
</h3>

| ステータス         | 終了済みか | 説明                          |
| ------------- | ----- | --------------------------- |
| `pending`     | いいえ   | タスクを受け付け、実行開始を待っている         |
| `in_progress` | いいえ   | タスクを実行中                     |
| `completed`   | はい    | タスクが完了し、`output` から結果を取得できる |
| `failed`      | はい    | タスクが失敗、失敗理由は `error` を参照    |
| `cancelled`   | はい    | タスクが取り消された                  |

**15 秒**ごとに 1 回照会し、ステータスが `completed`、`failed`、`cancelled` になるまで繰り返すことを推奨します。

<Note>
  `failed` または `cancelled` のタスクにも、すでに生成された一部の結果が含まれる場合があります。結果の有無を判断する際は、ステータスに加えて `output` が空かどうかも確認してください。
</Note>

***

<h2 id="query-tasks">
  タスクを照会する方法
</h2>

<h3 id="query-task-detail">
  タスク詳細の照会
</h3>

```bash theme={null}
curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

この API は照会時点の最新のタスク情報を返します。照会操作がタスクを変更することはなく、タスクのステータスはプラットフォームが自動的に更新します。

<h3 id="query-task-list">
  タスク一覧の照会
</h3>

作成レスポンスを失った場合や、過去のタスクをまとめて確認したい場合は、一覧 API で `task_id` を取得できます：

```bash theme={null}
curl "https://aihubmix.com/ai/v1/tasks?object=video&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

| パラメータ    | 型       | デフォルト値 | 説明                               |
| -------- | ------- | ------ | -------------------------------- |
| `object` | string  | -      | 種別でフィルタ：`llm`、`image`、`video`    |
| `status` | string  | -      | 統一されたタスクステータスでフィルタ               |
| `model`  | string  | -      | モデル名で完全一致フィルタ                    |
| `after`  | string  | -      | ページングカーソル、前ページの `next_after` を使用 |
| `limit`  | integer | `20`   | 1 ページあたりの件数、範囲は 1 ～ 100          |
| `order`  | string  | `desc` | `asc` または `desc`                 |

レスポンス例：

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "video",
      "model": "wan2.6-t2v",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}
```

| フィールド        | 説明                         |
| ------------ | -------------------------- |
| `object`     | 固定値 `list`、一覧レスポンスであることを示す |
| `data`       | 現在のページのタスク配列               |
| `has_more`   | 次のページがあるかどうか               |
| `next_after` | 次ページのカーソル、次のページがある場合のみ返される |

次のページを続けて取得する：

```bash theme={null}
curl "https://aihubmix.com/ai/v1/tasks?limit=20&order=desc&after=task_01K0ABCDEF" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

***

<h2 id="get-task-results">
  タスク結果を取得する方法
</h2>

<h3 id="single-artifact">
  単一成果物のタスク
</h3>

`output` にファイルが 1 つだけの場合は、直接アクセスできます：

```bash theme={null}
curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.bin
```

`output[0].content_url` をそのまま使用することもできます。ダウンロードレスポンスの `Content-Type` は `output[0].content_type` と一致します。

<h3 id="multiple-artifacts">
  複数成果物のタスク
</h3>

`output` に複数のファイルが含まれる場合は、対応する `result_id` を指定する必要があります：

```bash theme={null}
curl https://aihubmix.com/ai/v1/tasks/{task_id}/content/{result_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png
```

複数成果物のタスクで `result_id` を指定しない場合、API は `400 result_id_required` を返します。

<h3 id="llm-response-task">
  LLM レスポンスのタスク
</h3>

[LLM 中断リカバリー](#llm-interruption-recovery)の条件を満たしてレスポンスが保存された場合、タスクの `object` は `llm`、`output` 項目の `type` は `response` になります。コンテンツタイプは次のいずれかです：

* `application/json`：通常の JSON レスポンス
* `text/event-stream`：保存された SSE ストリーミングレスポンス

```bash theme={null}
curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

切り捨てのフラグはタスク詳細の `output[0].truncated` にあります。値が `true` の場合、保存されたレスポンスがサイズ制限により切り捨てられたことを示します。`GET /ai/v1/tasks/{task_id}/content` は元の JSON または SSE の内容を返し、その外側に `truncated` フィールドを付けることはありません。そのため、先にタスク詳細を照会してから内容を読み取ってください。

<Warning>
  結果には有効期限があり、ダウンロード回数の制限が設けられる場合もあります。`expires_at` より前に保存してください。期限切れの場合は `410 artifact_expired`、ダウンロード回数の上限を超えた場合は `429 too_many_downloads` を返します。
</Warning>

***

<h2 id="webhooks">
  Webhook を使用する方法
</h2>

現在、非同期タスクの作成時にタスク単位の Webhook を指定できます。タスク完了後に AIHubMix 側から通知してほしい場合は、非同期の画像または動画のリクエストボディに `webhook_url` と、任意で `webhook_events_filter` を指定してください：

```bash theme={null}
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A tranquil Japanese garden at sunrise",
    "seconds": "5",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'
```

コールバック URL は HTTPS を使用する必要があり、ローカルホスト、プライベートネットワーク、その他の制限対象アドレスを指すことはできません。

<h3 id="webhook-payload">
  コールバックリクエスト
</h3>

AIHubMix はコールバック URL へ `POST` リクエストを送信します：

```json theme={null}
{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-07-22T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}
```

| フィールド                | 説明                                           |
| -------------------- | -------------------------------------------- |
| `event_id`           | 当該コールバックイベントの一意な ID、重複通知の識別に使用               |
| `event_type`         | タスクの最終ステータス：`completed`、`failed`、`cancelled` |
| `created_at`         | コールバックイベントの作成時刻                              |
| `data.task_id`       | タスク ID、タスク詳細の照会に使用できる                        |
| `data.status`        | 現在のタスクステータス                                  |
| `data.model`         | タスク作成時に使用したモデル                               |
| `data.results[].url` | 生成済み結果のダウンロード URL                            |
| `data.error.code`    | 失敗時のエラーコード、失敗イベントにのみ含まれる場合がある                |
| `data.error.message` | 失敗の理由、失敗イベントにのみ含まれる場合がある                     |

`results` 内の URL にアクセスする際も、タスク作成時の API Key が必要です。

<h3 id="webhook-retry">
  リトライと重複排除
</h3>

AIHubMix はコールバックを少なくとも 1 回配信するため、同一イベントが重複して送信される場合があります：

* HTTP `2xx` は受信成功を示します。
* HTTP `5xx`、ネットワークエラー、タイムアウトはリトライの対象になります。
* HTTP `3xx` と `4xx` はリトライしません。
* 配信は最大 6 回、リトライ間隔は順に 1、4、16、64、256 秒です。

受信側は `event_id` を保存してください。同じ `event_id` を再度受信した場合は、業務ロジックをスキップして `2xx` を返してください。

<Warning>
  現在のタスク単位の Webhook では、設定可能な独立した署名用の資格情報を提供していません。通知を受け取った後は、タスク作成時の API Key で `GET /ai/v1/tasks/{task_id}` をリクエストし、照会結果を基準としてください。
</Warning>

***

<h2 id="error-codes">
  エラーレスポンスとエラーコード
</h2>

エラーレスポンスは統一された構造を使用します：

```json theme={null}
{
  "error": {
    "message": "Task not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0..."
  }
}
```

| フィールド           | 説明                                    |
| --------------- | ------------------------------------- |
| `error.message` | エラーの理由                                |
| `error.type`    | エラーの種別                                |
| `error.code`    | プログラムで識別できるエラーコード                     |
| `error.tid`     | リクエストのトレース ID、テクニカルサポートへ調査を依頼する際に提供する |

| HTTP ステータスコード | エラーコード                          | 説明                               |
| ------------- | ------------------------------- | -------------------------------- |
| 400           | `invalid_request`               | パラメータの型または値が正しくない                |
| 400           | `result_id_required`            | 複数成果物タスクで `result_id` が未指定       |
| 400           | `webhook_invalid`               | Webhook URL が不正                  |
| 400           | `webhook_events_filter_invalid` | Webhook のイベント一覧が不正               |
| 401           | `authentication_failed`         | API Key が未指定または無効                |
| 403           | `async_not_enabled`             | アカウントで非同期タスク機能が未有効               |
| 404           | `task_not_found`                | タスクが存在しない、または現在の API Key に属していない |
| 404           | `result_not_found`              | 結果が存在しない、または現在は取得できない            |
| 410           | `artifact_expired`              | 結果の有効期限が切れている                    |
| 429           | `too_many_downloads`            | 結果のダウンロード回数の上限を超えた               |
| 503           | `async_unavailable`             | 非同期画像サービスが一時的に利用できない、しばらくしてから再試行 |

***

<h2 id="full-example">
  完全なサンプル
</h2>

動画タスクの作成、ステータスのポーリング、全結果のダウンロードまでの一連のフローです：

<CodeGroup>
  ```python Python theme={null}
  import base64
  import os
  import time

  import requests

  BASE_URL = "https://aihubmix.com"
  API_KEY = os.environ["AIHUBMIX_API_KEY"]
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json",
  }

  # 1. タスクを作成
  response = requests.post(
      f"{BASE_URL}/ai/v1/videos",
      headers=HEADERS,
      json={
          "model": "wan2.6-t2v",
          "prompt": "A cat playing jazz on a piano",
          "seconds": "5",
          "size": "1280x720",
      },
      timeout=60,
  )
  response.raise_for_status()
  task = response.json()
  task_id = task["id"]

  # 2. タスクが完了、失敗、または取消になるまでポーリング
  while task["status"] not in {"completed", "failed", "cancelled"}:
      time.sleep(15)
      response = requests.get(
          f"{BASE_URL}/ai/v1/tasks/{task_id}",
          headers=HEADERS,
          timeout=30,
      )
      response.raise_for_status()
      task = response.json()
      print("status:", task["status"])

  # 3. 結果を取得
  if task["output"]:
      for index, item in enumerate(task["output"]):
          if encoded := item.get("b64_json"):
              with open(f"result-{index}.bin", "wb") as file:
                  file.write(base64.b64decode(encoded))
              continue
          result = requests.get(
              item["content_url"],
              headers=HEADERS,
              timeout=120,
          )
          result.raise_for_status()
          with open(f"result-{index}.bin", "wb") as file:
              file.write(result.content)
  elif task["status"] == "failed":
      raise RuntimeError(task.get("error"))
  ```

  ```typescript TypeScript theme={null}
  import { writeFile } from "node:fs/promises";

  const BASE_URL = "https://aihubmix.com";
  const HEADERS = {
    Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
    "Content-Type": "application/json",
  };

  // 1. タスクを作成
  const created = await fetch(`${BASE_URL}/ai/v1/videos`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({
      model: "wan2.6-t2v",
      prompt: "A cat playing jazz on a piano",
      seconds: "5",
      size: "1280x720",
    }),
  });
  let task = await created.json();

  // 2. タスクが完了、失敗、または取消になるまでポーリング
  const finished = new Set(["completed", "failed", "cancelled"]);
  while (!finished.has(task.status)) {
    await new Promise((resolve) => setTimeout(resolve, 15_000));
    const polled = await fetch(`${BASE_URL}/ai/v1/tasks/${task.id}`, {
      headers: HEADERS,
    });
    task = await polled.json();
    console.log("status:", task.status);
  }

  // 3. 結果を取得
  if (task.output?.length) {
    for (const [index, item] of task.output.entries()) {
      if (item.b64_json) {
        await writeFile(`result-${index}.bin`, Buffer.from(item.b64_json, "base64"));
        continue;
      }
      const result = await fetch(item.content_url, { headers: HEADERS });
      await writeFile(`result-${index}.bin`, Buffer.from(await result.arrayBuffer()));
    }
  } else if (task.status === "failed") {
    throw new Error(JSON.stringify(task.error));
  }
  ```

  ```shell curl theme={null}
  # 1. タスクを作成し、返された id を記録する
  curl -X POST https://aihubmix.com/ai/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-t2v",
      "prompt": "A cat playing jazz on a piano",
      "seconds": "5",
      "size": "1280x720"
    }'

  # 2. 15 秒ごとにステータスを照会する
  curl https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY"

  # 3. ステータスが completed になったら結果をダウンロードする
  curl https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    --output result.mp4
  ```
</CodeGroup>

***

<h2 id="faq">
  よくある質問（FAQ）
</h2>

**タスクのステータスはどのくらいの間隔で照会すべきですか？**

15 秒ごとに 1 回の照会を推奨します。高頻度のポーリングは避けてください。Webhook を使用する場合も、低頻度の照会をバックアップとして残しておくことを推奨します。

**作成レスポンスを失った場合、どうすればタスクを見つけられますか？**

タスク作成時と同じ API Key で `GET /ai/v1/tasks` をリクエストしてください。`object`、`model`、`status` で範囲を絞り込めます。

**同じアカウントの別の API Key でタスクを照会できないのはなぜですか？**

タスクは API Key 単位で分離されています。照会、ダウンロード、一覧のリクエストは、すべてタスク作成時と同じ Key を使用する必要があります。

**タスクが失敗したのに `output` が空配列でないのはなぜですか？**

一部のモデルは、全体が失敗または取消になる前に、引き渡し可能な結果をすでに生成している場合があります。`output` に `content_url` または `b64_json` が存在すれば、対応する方法で取得できます。

**Webhook が届かない場合はどうすればよいですか？**

コールバック URL が公開アクセス可能で HTTPS を使用しており、10 秒以内に `2xx` を返すことを確認してください。Webhook を使用しているかどうかにかかわらず、`GET /ai/v1/tasks/{task_id}` で最終ステータスを照会できます。

**LLM 中断リカバリーのために既存のコードを変更する必要はありますか？**

必要ありません。リクエストの方式、ストリーミングの挙動、レスポンス形式は変わりません。中断後にコンソールで該当タスクを正確に特定できるよう、レスポンスヘッダー `X-Aihubmix-Request-Id` を保存することを推奨します。

***

最終更新：2026-07-28