非同期画像生成

非同期生成とは

時間のかかる画像生成リクエストについて、プラットフォームは非同期生成モードをサポートしています。リクエスト送信後すぐにタスク 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 とマークします