動画タスクの作成

動画生成は非同期タスクです。作成成功はタスクが受理されたことのみを示すため、レスポンスの id を保存し、タスクの照会で進捗と結果を読み取る必要があります。1 回の作成リクエストは 1 つのタスクに対応し、照会やページの再読み込みで重複作成や二重課金が発生することはありません。

共通の取り決め（ベースアドレス、認証、レスポンス構造、レート制限、冪等性）は認証と基本仕様を参照してください。

エンドポイント一覧

用途	メソッド	パス	詳細ドキュメント
動画タスクの作成	POST	`/v1/video/generations`	本ページ
動画タスクの作成（OpenAI 互換形式）	POST	`/v1/videos`	本ページ
動画タスクの照会	GET	`/v1/video/generations/{task_id}`	動画タスクの照会
動画タスクの照会（OpenAI 互換形式）	GET	`/v1/videos/{task_id}`	動画タスクの照会

2 つの形式はリクエストボディ、レスポンスボディ、タスク ID が完全に同一で、どちらを選んでも構いません。同じタスク ID は両方のパスの組で照会できます。

既存のクライアントは引き続き /v1/video/generations を使用して構いません。プラットフォームは入口層でこれを /v1/videos の動画タスクプラグインとして処理するため、フィールドやパスを変更する必要はありません。

変数の準備

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_API_ORIGIN="https://locopalai.com"
export LOCOPAL_VIDEO_MODEL_ID="从 /v1/models 返回的视频模型 ID"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/reference.png"
export LOCOPAL_VIDEO_URL="https://你的对象存储域名/reference.mp4"
export LOCOPAL_AUDIO_URL="https://你的对象存储域名/reference.mp3"
export LOCOPAL_TASK_ID="创建视频后响应中的 id"

動画タスクの作成

POST/v1/video/generations

認証方式

Authorization: Bearer <API_KEY>。コンソールの「API キー」で作成したプラットフォーム API Key を使用します。

リクエストボディ · application/json

Prop

Type

prompt と content の少なくとも一方でテキスト入力を行う必要があります。content のみを送信した場合、プラットフォームは最初の type: "text" 要素の text をプロンプトとして使用します。model が欠落している場合は HTTP 400 を返します。詳細ページでサポートが明示されていないパラメータをモデルに渡さないでください。

content 要素

`type`	コンテンツフィールド	`role`	説明
`text`	`text`	省略	テキストプロンプト
`image_url`	`image_url.url`	`reference_image`	通常の参照画像。複数送信可能
`image_url`	`image_url.url`	`first_frame`	動画の先頭フレーム
`image_url`	`image_url.url`	`last_frame`	動画の末尾フレーム
`video_url`	`video_url.url`	`reference_video`	動作、カメラワーク、リズム、画面の参照動画
`audio_url`	`audio_url.url`	`reference_audio`	音声またはリズムの参照

公開素材は直接ダウンロード可能な HTTPS URL を使用する必要があり、Cookie、Referer、ログインページに依存できません。画像はモデルのサポート状況に応じて data:image/...;base64,... も使用できます。素材ライブラリでステータスが Active の素材は asset://<asset_id> を使用します。実在人物素材は実在人物素材ライブラリをサポートするモデルにのみ送信できます。

content 配列内の image_url、video_url、audio_url は元の型のまま上流へ渡されます。duration、ratio、resolution、seed、watermark、generate_audio などのトップレベルパラメータもタスクとともに送信され、metadata に追加で包む必要はありません。

通常の参照画像が 1 枚だけでよい場合は、トップレベルの image_url の省略記法も使用できます：

{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "prompt": "镜头缓慢推进",
  "image_url": "https://your-object-storage.example/reference.png",
  "duration": 5,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

プラットフォームはトップレベルの image_url を 1 つの参照画像コンテンツ項目に変換します。複数の画像、先頭・末尾フレーム、参照動画、参照音声が必要な場合は content 配列を使用してください。

リクエスト例

テキストから動画を生成

content は配列です。テキストは { "type": "text", "text": "..." }、参照画像は type: "image_url" を使用します。テキストのみの生成では text 項目を 1 つ置くだけで構いません。

resolution、ratio、duration は現在のモデルがサポートする段階値の範囲内である必要があります。 generate_audio と watermark はすべてのモデルが受け付けるわけではありません。

送信に成功した後は、返された id / task_id のみを使って照会し、タスクを作り直さないでください。

テキストのみから動画を生成

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    { "type": "text", "text": "雨后的城市街道，镜头从水面倒影缓慢抬升，电影感" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}
JSON

単一画像から動画を生成

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "人物自然转身，衣摆随风摆动，镜头轻微环绕" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/reference.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5
}

先頭・末尾フレーム

先頭フレームと末尾フレームはそれぞれ first_frame と last_frame とマークし、2 つの異なる画像を使用する必要があります。

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "镜头从室内平滑移动到窗外城市夜景" },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": { "url": "https://你的对象存储域名/first.png" }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": { "url": "https://你的对象存储域名/last.png" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

複数画像と参照動画

業務でよく言われる「深度動画」には公開エンドポイントに独立した deep_video フィールドはなく、参照動画として送信します。type に video_url、role に reference_video を使用します。各参照画像はそれぞれ 1 つの content 要素を占め、複数の URL を 1 つの image_url.url に入れることはできません。

curl -X POST "$LOCOPAL_API_ORIGIN/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "$LOCOPAL_VIDEO_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物为主体，沿用图片2的服装，参考视频的动作节奏和运镜，保持人物身份与产品外观一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "$LOCOPAL_IMAGE_URL" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://你的素材ID" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "https://你的对象存储域名/scene.png" }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": { "url": "$LOCOPAL_VIDEO_URL" }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 7,
  "generate_audio": false,
  "watermark": false
}
JSON

配列の順序が素材の順序です。プロンプトに「画像1、画像2、画像3、参照動画」と明示することを推奨し、サーバー側がファイル名から順序を推測することに依存しないでください。参照画像の枚数、参照動画、参照音声、出力解像度、長さはモデルの能力によって決まります。詳細は複数画像と参照動画の説明を参照してください。

複数画像、参照音声、固定シード

seed はサンプリング結果を固定できます。reference_audio は音声またはリズムの参照として使用します。duration、generate_audio、ratio、resolution、watermark はいずれもトップレベルパラメータです。以下の例はお客様でよく使われる 9:16 動画のパラメータに対応します：

{
  "model": "doubao-seedance-2.0-D",
  "content": [
    {
      "type": "text",
      "text": "以图片1的人物和服装为主体，参考图片2的另一名角色，参考音频的情绪和节奏生成电影感画面，保持角色身份一致。"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917114312-cyele" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260917111324-mquys" }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": { "url": "https://your-object-storage.example/reference.mp3" }
    }
  ],
  "duration": 9,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "watermark": false
}

作成成功後のレスポンスの id / task_id は引き続き非同期タスクのフローで照会します。参照音声はプラットフォームからアクセス可能な HTTPS アドレスである必要があり、asset:// 素材は事前に Active になっている必要があります。

レスポンスパラメータ

パラメータ	型	説明
`id`	string	公開タスク ID。タスク照会時に使用
`task_id`	string	`id` と同じ値の互換フィールド
`model`	string	今回のリクエストで使用したモデル ID
`status`	string	受理成功時は `queued`
`created_at`	integer	タスク作成時刻（Unix 秒）
`object`	string	任意。作成レスポンスでは省略される場合があり、照会成功後は通常 `video`
`progress`	integer	任意。作成レスポンスでは省略される場合があり、照会後に現在の進捗を返す

レスポンスボディ

{
  "created_at": 1789567067,
  "id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task_QH33zpW2IRHEnrmBbZFvtPzodyXvevWu"
}

作成レスポンスは固定のフィールド全集ではありません。クライアントは id / task_id が非空かどうかに依存するべきで、object や progress の存在を受理成功の必要条件とみなさないでください。

HTTP 200 とタスク ID を受け取った後は、ローカルでの待機がタイムアウトしても元のタスクを照会するだけにし、自動で作り直さないでください。

エラーレスポンス

パラメータ検証に通らない場合は HTTP 400 を返し、code は invalid_request で、message に欠落または誤記の内容が直接示されます：

{
  "code": "invalid_request",
  "message": "缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述",
  "data": null
}

残高または現在の API Key のクォータが今回の推定費用を賄えない場合は HTTP 403 を返し、タスクは作成されず、費用も発生しません：

{
  "code": "insufficient_user_quota",
  "message": "余额不足：本次预计需要 ＄11.500000，当前可用 ＄0.002000，请充值或调整参数后重试",
  "data": null
}

HTTP	よくある原因	対応
`400`	`model` の欠落、JSON 形式エラー、プロンプトの欠落、参照素材のロールまたはアドレスの誤記	`message` に従って修正してから再送信する
`401`	API Key の欠落、失効、使用権限なし	有効な Key に変更する
`403`	残高または現在の Key のクォータが推定費用を賄えない（`insufficient_user_quota`）	チャージするか、長さ/解像度などのパラメータを下げてから再送信する。この場合タスクは作成されない
`429`	処理中のタスクが並行上限に達した（`task_concurrency_exceeded`）	メッセージ内の「現在 N 件 / 上限 M」に従い、既存タスクの完了を待ってから送信する
`429`	現在のグループの上流負荷が飽和しているか、リクエスト頻度が制限されている	しばらくしてからリトライし、並行した重複送信を避ける
`500`	タスク作成の失敗	エラーコードを読む。タスク ID がある場合は元のタスクの照会を続ける
`503`	現在のモデルが利用不可	`/v1/models` を再照会し、利用可能なモデルに切り替えるか、しばらくしてから再試行する

並行数と送信のペース

生成タスクはバックグラウンドで並行実行され、送信と結果のダウンロードはいずれもプラットフォームの出口帯域を消費するため、プラットフォームは同時に処理中のタスク数に上限を設けています。各アカウントで同時に最大 2000 個です。上限に達した後に送信すると次が返ります：

{
  "code": "task_concurrency_exceeded",
  "message": "当前账号有 2000 个生成任务正在处理中，已达到并发上限 2000，请等待任务完成后再提交",
  "data": null
}

バッチタスクは次のように編成することを推奨します：

まず 1 バッチ送信し、タスクが completed / failed の終端状態になってから次のバッチを送信してください。ループで同じリクエストを連続リトライしないでください。
1 回の送信で参照画像が多いほど、解像度が高いほど出口帯域を占有する時間が長くなるため、同時に送信するタスクをそれに応じて減らしてください。
同時に複数の動画を生成する必要がある場合は、タスク ID ごとに進捗を記録し、前のバッチの完了を待ってから続行してください。重複送信による二重課金を避けてください。

課金とパラメータ検証

動画タスクは完了時に実際の使用量で精算されます。作成成功はタスクが受理されたことのみを示し、送信段階では事前に課金されず、請求記録も一切発生しません。タスク完了後、請求には実際の課金記録が 1 件だけ現れます。
送信時にアカウント残高（または現在の API Key のクォータ）が今回の推定クォータを賄えるか検証します。不足している場合は HTTP 403 と insufficient_user_quota を返し、エラーメッセージに「今回の予想必要額 …、現在の利用可能額 …」が示されます。残高を補充するかパラメータを調整してから再送信してください。この場合タスクは作成されず、費用も発生しません。
送信前にリクエストボディを検証し、内容が欠けている場合はそのまま読めるヒントを返すため、上流のエラーで原因を特定する必要はありません：

メッセージ	原因	対応
`缺少提示词：请在 prompt 或 content 的 text 元素中提供文本描述`	テキスト記述がない	`prompt` を補うか、`content` に `type: "text"` 要素を追加する
`content[0].role 不支持 "xxx"，可用值：reference_image、first_frame、last_frame、reference_video、reference_audio`	参照素材のロールが誤っている	メッセージに従って許可されたロールに変更する
`content[0].image_url.url 不能为空`	参照素材のアドレスが空	`asset://<素材ID>`、公開ダウンロード可能な HTTPS アドレス、または `data:` インラインデータを記入する
`content[0] 参考素材不可用：地址需要是 https:// 公网地址、asset://<素材ID> 或 data: 内联数据`	素材アドレスのプロトコルが未対応	プラットフォームの素材 ID、HTTPS 直リンク、または `data:` インラインデータに変更する。`ftp://`、`file://`、内部ネットワークアドレスは使用しない
`content[0] 参考素材不可用：素材库中找不到素材 xxx`	`asset://` 素材が存在しない、または現在のアカウントに属さない	まず素材ライブラリに送信し、利用可能な状態になるまで待つか、アカウントを確認する
`duration 必须大于 0`	長さパラメータが不正	モデルがサポートする長さに変更する

このページの目次