task_id を即時に返し、クライアントが中断した LLM リクエストはプラットフォーム側が処理を継続して最終レスポンスを保存します。3 種類とも同じタスクステータス、照会 API、結果ダウンロードのフローを共有します。
タスクの照会と結果のダウンロードには、タスク作成時と同じ API Key を使用してください。タスクは API Key 単位で分離されており、2 つの Key が同じアカウントに属していても相互に読み取ることはできません。
コンソールで非同期タスクを有効化する
非同期の画像または動画を作成する前に、現在のアカウントで非同期タスク機能を有効化してください。コンソールにこの入口が表示されていない場合は、AIHubMix テクニカルサポートへお問い合わせください。
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 はデフォルトで同期的に返します。async を true に設定すると、API はタスクオブジェクトを即時に返し、生成処理はバックグラウンドで継続されます。
async はブール値である必要があります。指定しない場合や false に設定した場合、画像 API は同期的な動作を維持します。
5.2 非同期動画
動画 API は常に非同期です。作成に成功するとpending または in_progress のステータスを返します。Prefer: wait による同期待機への変更には対応していません。
5.3 共通パラメータ
サンプル内のmodel、prompt、n、seconds、size は一般的なモデルパラメータです。各モデルが対応するフィールドと値は、対応するモデルの API ドキュメントを基準としてください。動画モデルについては動画生成のドキュメントを参照できます。以下の表は、すべての非同期タスクで共通のパラメータのみを説明します。
画像タスクで Webhook を使用できるのは
async: true の場合のみです。webhook_events_filter を省略すると、AIHubMix は completed、failed、cancelled の 3 つの最終ステータスをプッシュします。指定する場合は webhook_url と併せて使用する必要があり、空や重複は指定できません。6. LLM 中断リカバリーはどのように機能するか
LLM 中断リカバリーは、クライアントが接続を切断した後の最終レスポンスを取得するための機能です。この機能は既存の LLM リクエスト方式をそのまま利用し、ストリーミングの挙動とレスポンス形式は変わりません。追加の作成 API を呼び出す必要はなく、事前にtask_id が返されることもありません。
6.1 有効になる条件
以下の条件をすべて満たす必要があります:
対応するインターフェース:
呼び出し時に追加フィールドを渡す必要はありません。対応範囲は 4.3 LLM 中断リカバリーを参照してください。表に記載されていないモデルは、本番導入前に低コストのリクエストを 1 件使って中断リカバリーの検証を行えます。検証用のリクエストも通常どおり課金されます。いずれかの条件を満たさない場合、リクエストは通常どおり実行されますが、クライアントが中断しても
llm タスクは生成されません。6.2 中断後の実行フロー
6.3 対応する中断リクエストを特定する
LLM のレスポンスヘッダーにはX-Aihubmix-Request-Id が返されます。クライアントはレスポンスヘッダーを受け取った時点でこの値を保存してください。中断が発生した後は、AIHubMix コンソールの非同期タスク一覧でこのリクエスト ID を使って該当タスクを検索できます。
公開されているタスク API は現時点でリクエスト ID によるフィルタリングに対応していません。リクエスト ID を保存していない場合は、リクエスト作成時と同じ API Key を使い、モデルと作成時刻で検索する方法のみとなります:
7. タスクオブジェクトとステータス
すべてのタスクは統一されたレスポンス構造を使用します:output 内の結果フィールド:
7.1 ステータスの説明
15 秒ごとに 1 回照会し、ステータスが
completed、failed、cancelled になるまで繰り返すことを推奨します。
failed または cancelled のタスクにも、すでに生成された一部の結果が含まれる場合があります。結果の有無を判断する際は、ステータスに加えて output が空かどうかも確認してください。8. タスクを照会する方法
8.1 タスク詳細の照会
8.2 タスク一覧の照会
作成レスポンスを失った場合や、過去のタスクをまとめて確認したい場合は、一覧 API でtask_id を取得できます:
レスポンス例:
次のページを続けて取得する:
9. タスク結果を取得する方法
9.1 単一成果物のタスク
output にファイルが 1 つだけの場合は、直接アクセスできます:
output[0].content_url をそのまま使用することもできます。ダウンロードレスポンスの Content-Type は output[0].content_type と一致します。
9.2 複数成果物のタスク
output に複数のファイルが含まれる場合は、対応する result_id を指定する必要があります:
result_id を指定しない場合、API は 400 result_id_required を返します。
9.3 LLM レスポンスのタスク
LLM 中断リカバリーの条件を満たしてレスポンスが保存された場合、タスクのobject は llm、output 項目の type は response になります。コンテンツタイプは次のいずれかです:
application/json:通常の JSON レスポンスtext/event-stream:保存された SSE ストリーミングレスポンス
output[0].truncated にあります。値が true の場合、保存されたレスポンスがサイズ制限により切り捨てられたことを示します。GET /ai/v1/tasks/{task_id}/content は元の JSON または SSE の内容を返し、その外側に truncated フィールドを付けることはありません。そのため、先にタスク詳細を照会してから内容を読み取ってください。
10. Webhook を使用する方法
現在、非同期タスクの作成時にタスク単位の Webhook を指定できます。タスク完了後に AIHubMix 側から通知してほしい場合は、非同期の画像または動画のリクエストボディにwebhook_url と、任意で webhook_events_filter を指定してください:
10.1 コールバックリクエスト
AIHubMix はコールバック URL へPOST リクエストを送信します:
results 内の URL にアクセスする際も、タスク作成時の API Key が必要です。
10.2 リトライと重複排除
AIHubMix はコールバックを少なくとも 1 回配信するため、同一イベントが重複して送信される場合があります:- HTTP
2xxは受信成功を示します。 - HTTP
5xx、ネットワークエラー、タイムアウトはリトライの対象になります。 - HTTP
3xxと4xxはリトライしません。 - 配信は最大 6 回、リトライ間隔は順に 1、4、16、64、256 秒です。
event_id を保存してください。同じ event_id を再度受信した場合は、業務ロジックをスキップして 2xx を返してください。
11. エラーレスポンスとエラーコード
エラーレスポンスは統一された構造を使用します:12. 完全なサンプル
動画タスクの作成、ステータスのポーリング、全結果のダウンロードまでの一連のフローです:よくある質問(FAQ)
タスクのステータスはどのくらいの間隔で照会すべきですか? 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