Skip to main content
動画生成やバッチ画像生成のようなリクエストは、1 回の HTTP 接続で待てる時間を超えることが一般的です。また、長文生成の途中でクライアントが切断すると、すでに生成された部分のレスポンスも取り戻せません。 非同期タスク(Async Tasks)は、この 3 つのシナリオを同一のタスクオブジェクトに統一します。画像と動画は生成 API でタスクを作成して task_id を即時に返し、クライアントが中断した LLM リクエストはプラットフォーム側が処理を継続して最終レスポンスを保存します。3 種類とも同じタスクステータス、照会 API、結果ダウンロードのフローを共有します。
タスクの照会と結果のダウンロードには、タスク作成時と同じ API Key を使用してください。タスクは API Key 単位で分離されており、2 つの Key が同じアカウントに属していても相互に読み取ることはできません。

コンソールで非同期タスクを有効化する

非同期の画像または動画を作成する前に、現在のアカウントで非同期タスク機能を有効化してください。コンソールにこの入口が表示されていない場合は、AIHubMix テクニカルサポートへお問い合わせください。
非同期タスク機能が有効化されていない場合、メディアタスクの作成リクエストは 403 async_not_enabled を返します。LLM リクエストはこれによってエラーにはなりませんが、クライアントが中断した後に最終レスポンスを取り戻すことはできません。

1. クイックスタート

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

2. 同期呼び出し vs 非同期タスクの比較

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

3. インターフェース概要

Base URL:https://aihubmix.com、認証方式は Bearer Token です:
/ai/v1/tasks は読み取り専用の統一照会入口であり、POST /ai/v1/tasks は提供していません。画像と動画はそれぞれ対応する生成 API で作成します。LLM 中断リカバリーの条件を満たすリクエストは、クライアントが中断した後に llm タスクとして自動的に記録されます。

4. 対応モデル

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

4.1 非同期画像

4.2 非同期動画

4.3 LLM 中断リカバリー

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

5. 非同期タスクを作成する方法

5.1 非同期画像

画像 API はデフォルトで同期的に返します。asynctrue に設定すると、API はタスクオブジェクトを即時に返し、生成処理はバックグラウンドで継続されます。
async はブール値である必要があります。指定しない場合や false に設定した場合、画像 API は同期的な動作を維持します。

5.2 非同期動画

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

5.3 共通パラメータ

サンプル内の modelpromptnsecondssize は一般的なモデルパラメータです。各モデルが対応するフィールドと値は、対応するモデルの API ドキュメントを基準としてください。動画モデルについては動画生成のドキュメントを参照できます。以下の表は、すべての非同期タスクで共通のパラメータのみを説明します。
画像タスクで Webhook を使用できるのは async: true の場合のみです。webhook_events_filter を省略すると、AIHubMix は completedfailedcancelled の 3 つの最終ステータスをプッシュします。指定する場合は webhook_url と併せて使用する必要があり、空や重複は指定できません。

6. LLM 中断リカバリーはどのように機能するか

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

6.1 有効になる条件

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

6.2 中断後の実行フロー

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

6.3 対応する中断リクエストを特定する

LLM のレスポンスヘッダーには X-Aihubmix-Request-Id が返されます。クライアントはレスポンスヘッダーを受け取った時点でこの値を保存してください。中断が発生した後は、AIHubMix コンソールの非同期タスク一覧でこのリクエスト ID を使って該当タスクを検索できます。 公開されているタスク API は現時点でリクエスト ID によるフィルタリングに対応していません。リクエスト ID を保存していない場合は、リクエスト作成時と同じ API Key を使い、モデルと作成時刻で検索する方法のみとなります:
同一の API Key で同じモデルへ複数のリクエストを並行して送信した場合、モデルと作成時刻だけでは正確な対応付けを保証できません。確実にリカバリーする必要がある場合は X-Aihubmix-Request-Id を保存し、コンソールで検索してください。レスポンスヘッダーを取得できていない場合、一覧の最新タスクをそのまま当該リクエストのものと判断することは避けてください。
LLM 中断リカバリーのタスクは現時点で Webhook を送信しません。結果はタスク一覧から照会してください。クライアントの中断によってプラットフォーム側の処理継続が止まることはなく、その呼び出しは元の LLM API のルールどおりに課金されます。

7. タスクオブジェクトとステータス

すべてのタスクは統一されたレスポンス構造を使用します:
output 内の結果フィールド:

7.1 ステータスの説明

15 秒ごとに 1 回照会し、ステータスが completedfailedcancelled になるまで繰り返すことを推奨します。
failed または cancelled のタスクにも、すでに生成された一部の結果が含まれる場合があります。結果の有無を判断する際は、ステータスに加えて output が空かどうかも確認してください。

8. タスクを照会する方法

8.1 タスク詳細の照会

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

8.2 タスク一覧の照会

作成レスポンスを失った場合や、過去のタスクをまとめて確認したい場合は、一覧 API で task_id を取得できます:
レスポンス例:
次のページを続けて取得する:

9. タスク結果を取得する方法

9.1 単一成果物のタスク

output にファイルが 1 つだけの場合は、直接アクセスできます:
output[0].content_url をそのまま使用することもできます。ダウンロードレスポンスの Content-Typeoutput[0].content_type と一致します。

9.2 複数成果物のタスク

output に複数のファイルが含まれる場合は、対応する result_id を指定する必要があります:
複数成果物のタスクで result_id を指定しない場合、API は 400 result_id_required を返します。

9.3 LLM レスポンスのタスク

LLM 中断リカバリーの条件を満たしてレスポンスが保存された場合、タスクの objectllmoutput 項目の typeresponse になります。コンテンツタイプは次のいずれかです:
  • application/json:通常の JSON レスポンス
  • text/event-stream:保存された SSE ストリーミングレスポンス
切り捨てのフラグはタスク詳細の output[0].truncated にあります。値が true の場合、保存されたレスポンスがサイズ制限により切り捨てられたことを示します。GET /ai/v1/tasks/{task_id}/content は元の JSON または SSE の内容を返し、その外側に truncated フィールドを付けることはありません。そのため、先にタスク詳細を照会してから内容を読み取ってください。
結果には有効期限があり、ダウンロード回数の制限が設けられる場合もあります。expires_at より前に保存してください。期限切れの場合は 410 artifact_expired、ダウンロード回数の上限を超えた場合は 429 too_many_downloads を返します。

10. Webhook を使用する方法

現在、非同期タスクの作成時にタスク単位の Webhook を指定できます。タスク完了後に AIHubMix 側から通知してほしい場合は、非同期の画像または動画のリクエストボディに webhook_url と、任意で webhook_events_filter を指定してください:
コールバック URL は HTTPS を使用する必要があり、ローカルホスト、プライベートネットワーク、その他の制限対象アドレスを指すことはできません。

10.1 コールバックリクエスト

AIHubMix はコールバック URL へ POST リクエストを送信します:
results 内の URL にアクセスする際も、タスク作成時の API Key が必要です。

10.2 リトライと重複排除

AIHubMix はコールバックを少なくとも 1 回配信するため、同一イベントが重複して送信される場合があります:
  • HTTP 2xx は受信成功を示します。
  • HTTP 5xx、ネットワークエラー、タイムアウトはリトライの対象になります。
  • HTTP 3xx4xx はリトライしません。
  • 配信は最大 6 回、リトライ間隔は順に 1、4、16、64、256 秒です。
受信側は event_id を保存してください。同じ event_id を再度受信した場合は、業務ロジックをスキップして 2xx を返してください。
現在のタスク単位の Webhook では、設定可能な独立した署名用の資格情報を提供していません。通知を受け取った後は、タスク作成時の API Key で GET /ai/v1/tasks/{task_id} をリクエストし、照会結果を基準としてください。

11. エラーレスポンスとエラーコード

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

12. 完全なサンプル

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

よくある質問(FAQ)

タスクのステータスはどのくらいの間隔で照会すべきですか? 15 秒ごとに 1 回の照会を推奨します。高頻度のポーリングは避けてください。Webhook を使用する場合も、低頻度の照会をバックアップとして残しておくことを推奨します。 作成レスポンスを失った場合、どうすればタスクを見つけられますか? タスク作成時と同じ API Key で GET /ai/v1/tasks をリクエストしてください。objectmodelstatus で範囲を絞り込めます。 同じアカウントの別の API Key でタスクを照会できないのはなぜですか? タスクは API Key 単位で分離されています。照会、ダウンロード、一覧のリクエストは、すべてタスク作成時と同じ Key を使用する必要があります。 タスクが失敗したのに output が空配列でないのはなぜですか? 一部のモデルは、全体が失敗または取消になる前に、引き渡し可能な結果をすでに生成している場合があります。outputcontent_url または b64_json が存在すれば、対応する方法で取得できます。 Webhook が届かない場合はどうすればよいですか? コールバック URL が公開アクセス可能で HTTPS を使用しており、10 秒以内に 2xx を返すことを確認してください。Webhook を使用しているかどうかにかかわらず、GET /ai/v1/tasks/{task_id} で最終ステータスを照会できます。 LLM 中断リカバリーのために既存のコードを変更する必要はありますか? 必要ありません。リクエストの方式、ストリーミングの挙動、レスポンス形式は変わりません。中断後にコンソールで該当タスクを正確に特定できるよう、レスポンスヘッダー X-Aihubmix-Request-Id を保存することを推奨します。
最終更新:2026-07-28