動画タスクの照会

タスク作成後は、作成レスポンスの id を使用して進捗と結果を照会します。作成方法は動画タスクの作成を参照してください。

ステータスの照会：GET /v1/video/generations/{task_id}

完成動画のダウンロード：GET /v1/videos/{task_id}/content

照会エンドポイントはタスク完了後、metadata.url に動画アドレスを返します。プラットフォームは上流の元の動画アドレスを優先して返し、上流に利用可能なアドレスがない場合にのみ、access 機能付きのプラットフォーム成果物アドレスにフォールバックします。上流の元のアドレスは署名と有効期限が付いている場合があり、ブラウザやプレーヤーで直接開けます。プラットフォーム成果物アドレスも同様に利用できます。API Key を付けて /v1/videos/{task_id}/content を呼び出し、動画ファイルをダウンロードすることもできます。

認証方式

Authorization: Bearer <API_KEY>。

リクエストパラメータ · path

リクエスト例

curl "$LOCOPAL_API_ORIGIN/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

動画のダウンロード

タスクステータスが completed になったら、照会レスポンスの metadata.url を直接使用します：

curl -L "$LOCOPAL_API_ORIGIN/v1/videos/$LOCOPAL_TASK_ID/content" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -o "$LOCOPAL_TASK_ID.mp4"

レスポンスパラメータ

レスポンスボディ

実行中：

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1787299277
}

生成成功：

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "completed",
  "progress": 100,
  "created_at": 1787299277,
  "completed_at": 1787299581,
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800,
  "metadata": {
    "url": "https://upstream.example.com/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO.mp4?signature=...",
    "upstream_created": true
  },
  "usage": {
    "prompt_tokens": 141034,
    "completion_tokens": 0,
    "total_tokens": 141034,
    "quota": 2789652,
    "amount": 5.579304,
    "currency": "CNY"
  }
}

usage はタスク完了・精算後にのみ返され、値は請求におけるこのタスクの課金と完全に一致します。usage.quota は今回消費したクォータ、usage.amount は同じクォータを現在のサイトの為替レートで換算した人民元金額、usage.total_tokens は今回課金対象の動画 token 数です。タスクがまだキュー待ちや生成中の場合 usage は返されないため、その際に照会レスポンスから費用を判断しないでください。課金を照合する必要がある場合は、同じ id でコンソールの請求と usage.quota および usage.amount を比較してください。

metadata.url は署名付きの上流アドレスの場合も、プラットフォーム成果物エンドポイントがフォールバックする場合もあります。資格情報として扱い、公開して共有しないでください。完成した動画は、expires_at より前にダウンロードするか、自分のオブジェクトストレージへ転存することを推奨します。

動画成果物とプレビュー

metadata.url を直接読み取るほか、プラットフォームの成果物一覧を照会することもできます：

curl "$LOCOPAL_API_ORIGIN/v1/tasks/$LOCOPAL_TASK_ID/artifacts" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

タスク完了後に返されます：

{
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://locopalai.com/v1/tasks/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO/artifacts/video/content?access=..."
    }
  ]
}

成果物コンテンツのアドレスは Range リクエストをサポートします。プレーヤー、ブラウザでのプレビュー、レジュームダウンロードにそのまま使用できます。クライアントが metadata.url のみを読み取る場合は、従来のロジックをそのまま使用してよく、成果物エンドポイントに変更する必要はありません。

生成失敗：

{
  "id": "task_NlersigX6rIqiOjCwTFlgNmGMTwqt39K",
  "object": "video",
  "model": "doubao-seedance-2.0-D",
  "status": "failed",
  "progress": 100,
  "created_at": 1789971935,
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  },
  "metadata": {
    "submission_stage": "submitting",
    "upstream_created": false
  }
}

error.message はプラットフォームが整理した最終的な失敗メッセージです。過去のタスクが最初にネストした JSON を保存していた場合でも、照会時には正規化されたテキストが返されます。呼び出し元はこのフィールドをそのままユーザーに表示すればよく、クライアント側で元の上流 JSON を再結合したり解析したりしないでください。

エラーレスポンス

存在しないタスク ID（または現在のアカウントに属さないタスク）を照会すると HTTP 400 を返します：

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

ステータスの処理

クライアントは固定の待機秒数で完了を判断しないでください。また、一度のネットワークタイムアウトでタスクを重複作成しないでください。5～15 秒に 1 回の照会を推奨します。

参照素材の読み取り失敗

エラーが content[n].image_url、video_url を指す場合、または resource download failed を含む場合は、まず配列の添字で該当要素を特定し、次を確認してください：

1. URL が公網から直接 GET でき、200 を返すか。
2. ログインページへリダイレクトするか、Cookie、Referer、IP 許可リストに依存しているか。
3. Content-Type がファイルの実際の形式と一致しているか。
4. 一時的な署名付き URL がダウンロードと処理の間も有効か。
5. asset:// 素材が現在のアカウントに属し、ステータスが Active か。
6. 現在のモデルがその素材の種類と数量をサポートしているか。

素材を修正してからタスクを作り直してください。エラーメッセージはユーザーに読める原因を 1 回表示するだけでよく、多層にエスケープされた JSON を繰り返し結合して表示しないでください。

並行数、リトライ、課金

• 異なる動画タスクは並行して作成できます。
• 同じ作成レスポンスに対しては、必ず同じタスク ID で照会してください。
• タスクが明確に失敗し、ユーザーが自らリトライした場合にのみ、新しい作成リクエストを発行してください。
• 課金はモデル、解像度、長さ、参照動画の入力によって細分化され、モデルマーケットと最終的な請求に準じます。パラメータ検証の失敗（400）はリクエストが受理されなかったことを示し、通常は生成タスクの費用は発生しません。

関連ドキュメント