非同期生成とは
時間のかかる画像生成リクエストについて、プラットフォームは非同期生成モードをサポートしています。リクエスト送信後すぐにタスク ID が返され、クライアントはポーリングで最終結果を取得します。長時間接続を維持する必要はありません。
非同期モードは生成時間が長いシナリオに適しており、リクエストのタイムアウト中断を防げます。複数タスクの一括送信にも便利です。
使用フロー
非同期生成は 3 ステップ:タスク送信 → 状態ポーリング → 結果取得。
1. タスク送信
https://api.tvtapi.com/v1/images/async に POST リクエストを送信し、API Key(Bearer 認証)とリクエストパラメータを含めます:
curl -X POST https://api.tvtapi.com/v1/images/async \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"model-name","prompt":"説明テキスト"}'
レスポンスに task_id が含まれます。これが以降の照会とダウンロードの唯一の証憑です。
2. 状態ポーリング
task_id でタスク状態をポーリング:
curl https://api.tvtapi.com/v1/images/async/{task_id} \
-H "Authorization: Bearer sk-xxxxxxxx"
タスク状態:queued(待機中)、in_progress(生成中)、succeeded(成功)、failed(失敗)。数秒ごとにポーリングし、状態が succeeded または failed になるまで繰り返します。
3. 画像ダウンロード
タスク成功後、以下のアドレスで画像を取得:
curl -L https://api.tvtapi.com/v1/images/async/{task_id}/content \
-H "Authorization: Bearer sk-xxxxxxxx"
このエンドポイントは画像の実際の保存先へ 302 リダイレクトします。各画像にはダウンロード回数制限があり、タイムアウト後にタスクは自動的に期限切れとなります。
ウェブ版でも使用可能
コードを書きたくない場合は、/ja-jp/user/image-studio の画像ワークベンチを直接使用できます。ワークベンチには非同期モードの切り替え機能が内蔵されており、有効化するとページ内で自動的にポーリングして結果を表示します。
注意事項
- 非同期機能は管理者がバックエンドで有効化する必要があり、ユーザーアカウントにも該当権限が必要です
- タスクには有効期限があり、期限切れ後はダウンロードできません
- 長時間
in_progressのままだと、システムが自動的にタイムアウトしfailedとマークします