複数画像と参照動画の説明

本ページでは、「複数の参照画像＋1 つの参照動画」のプログラミングによる連携について、機能の境界、順序のルール、深度動画、音声、タスクの復元、課金を説明します。リクエストボディの完全なフィールド表とコピー可能な例は動画生成エンドポイント、素材の登録は素材ライブラリ APIを参照してください。

先に結論

• 複数の画像と 1 つの参照動画は同じ content 配列を使用します。各画像が 1 つの image_url 要素を占め、動画が 1 つの video_url 要素を占めます。
• 「深度動画」には独立した deep_video フィールドはなく、通常の参照動画として送信し、role に reference_video を使用します。
• 配列の順序が素材の順序です。プロンプトに「画像1、画像2、画像3、参照動画」と明示することを推奨し、サーバー側がファイル名から順序を推測することに依存しないでください。
• generate_audio: false は生成結果の音声出力をオフにすることを意味し、入力参照動画の元の音声トラックを保持することとは異なり、入力音声を完成映像にコピーすることでもありません。
• 正確な画像枚数、動画数、ファイルサイズ、エンコード、並行数の上限は、モデルカタログと実際のエンドポイントレスポンスに準じます。プラットフォームはすべての Seedance バリアントに対して統一的な上限を約束しているわけではありません。
• 元映像の動き、カメラ位置、カット割りを必ず保持する必要がある場合、参照動画はモデルの参照としてのみ機能します。現在の公開リクエストには「N 秒目で強制的にカットする」といった汎用パラメータはなく、正確なタイミングはエンドポイントのフィールドだけでは保証できません。

一、現在のモデル能力の確認

まず、現在のキーで参照可能なモデルカタログを読み取ります：

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

カタログは「モデルが参照可能か、どのエンドポイントで利用できるか」を確認するだけのもので、リクエスト時に model に入力するのは data[].id です。参照画像の枚数、参照動画、参照音声、出力比率、長さ、解像度などの具体的な制限は、モデル詳細ページとエンドポイントが返すパラメータエラーに準じます。カタログに記載されていない制限について、プラットフォームがモデルに代わって推測することはありません。

二、参照素材の登録と参照

架空の人物設定画像、キャラクターの多視点画像、人物のいないシーン画像は実在人物の許諾素材ではなく、通常のバーチャル素材として登録します：

POST /api/v1/materials/groups
POST /api/v1/materials/assets
GET  /api/v1/materials/assets/{asset_id}

素材ステータスが Active になったら、動画リクエストの画像 URL を次のように変更できます：

asset://asset-20260911035115-etexu

画像を 1 枚ずつ登録すると、それぞれに独立した asset_id が付与されます。人物画像とシーン画像は同じバーチャルグループに置いても、別々のグループを作成しても構いません。動画送信時は異なる content 要素で参照します。登録、ポーリング、エラーレスポンスは素材ライブラリ APIを参照してください。

送信成功時の status は通常 Processing で、処理が完了すると Active になります。失敗時は status が Failed になり、error_message に理由が示されます。審査は非同期処理で、プラットフォームはすべての画像に対して一律の時間を約束していません。プログラムは同じ asset_id を照会し、Processing の間に重複して送信しないでください。

三、複数画像＋1 つの参照動画

次のリクエストは「人物画像 1 枚＋シーン画像 2 枚＋参照動画 1 本」を表します。配列のインデックスは 1 から説明します：

1. content[1] は画像1、人物画像です。
2. content[2] は画像2、シーン画像1です。
3. content[3] は画像3、シーン画像2です。
4. content[4] は参照動画です。

content[0] はテキストプロンプトで、画像の番号には含まれません。

{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    {
      "type": "text",
      "text": "图片1是人物身份参考，图片2和图片3是场景参考。参考视频用于动作、机位和镜头节奏参考；保持人物身份和场景关系一致。"
    },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://人物素材ID" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID1" } },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://场景素材ID2" } },
    { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://你的对象存储域名/reference-depth.mp4" } }
  ],
  "duration": 7,
  "resolution": "720p",
  "ratio": "9:16",
  "generate_audio": false,
  "watermark": false
}

作成に成功するとタスク ID が返るので、以降はこのタスクのみを照会します：

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

レスポンスが現在のモデルで素材ライブラリをサポートしていないことを明確に示している場合は、そのモデルがサポートする公開 HTTPS 画像アドレスに変更するか、モデルを変更してください。素材の審査を回避しないでください。完全な作成・照会レスポンスの例は動画生成エンドポイントを参照してください。

四、参照動画、音声、深度動画の境界

参照動画は正確な制御トラックではありません

グレースケール深度動画は公開エンドポイントの構造上、引き続き通常の reference_video です。現在のモデル詳細が深度制御機能を個別に宣言していない限り、プラットフォームはグレースケール値を深度制約として解釈せず、元動画の深度、動きの軌跡、カット割りを厳密に複製することも保証しません。

参照動画はモデルが動き、カメラ位置、構図、リズムを理解する助けになりますが、完成映像はモデルによって再生成されます。現在の公開リクエストには汎用的なタイムコードトラックや強制カットフィールドはありません。特定の時点に近いカットが必要な場合は、プロンプトで説明し、生成後に完成映像を確認するしかありません。フレーム単位の正確さが必須の場合は、外部の編集または合成段階で行ってください。

入力音声トラックと generate_audio

参照動画に元の音声トラックがある場合、モデルがその音声トラックを読み取るかどうかは、現在のモデルの参照動画の実装によって異なります。generate_audio: false の確定した意味は生成結果の音声出力をオフにすることであり、入力動画の音声トラックをコピーすることや、入力音声トラックを独立した参照音声として使用することを約束するものではありません。

• 「無音の動画を生成する」ことが目的の場合は、generate_audio: false を指定できます。
• 「元映像の音声を保持する」ことが目的の場合は、このフィールドだけに頼らず、完成映像のダウンロード後に独自の音声・映像合成フローで処理するか、参照音声と出力音声を明確にサポートする設定をモデル詳細から選択してください。
• モデル詳細が参照音声のサポートを宣言していない場合は、reference_audio を追加で送信しないでください。

五、現在一律に約束できない制限

「現在のグループがこのリクエスト群をサポートするか」について

呼び出しグループと素材ライブラリのグループは 2 つの異なる概念であり、コンソールのグループ名だけで複数画像や参照動画をサポートするかどうかを判断することはできません。実際の判断順序は次のとおりです：

1. /v1/models に選択したモデルが存在する。
2. モデル詳細が参照画像と参照動画を明確に許可している。
3. 参照する素材のステータスが Active である。
4. 作成エンドポイントが queued を返し、リクエストが受理されたことを示す。
5. 最終的に failed になった場合は、error.code と error.message を読み取って組み合わせまたは素材の問題を判断する。

プラットフォームは参照動画をサポートしないモデルを別のモデルに無言で切り替えることはなく、予期しない費用や結果を避けます。

六、タスクの復元、レート制限、冪等性、課金

照会と復元

作成エンドポイントが id を返したらすぐに保存する必要があり、ネットワークが中断してもタスク ID を取得済みであれば元のタスクのみを照会します。現在の公開エンドポイントには「プロンプト＋素材＋パラメータ」でタスクを逆引きする汎用的な方法はありません。作成レスポンスが返る前に接続が中断し、タスク ID がない場合、プラットフォームはリクエスト本文だけで元のタスクを検索できることを保証できません。そのため、呼び出し側は自身のデータベースに業務リクエストを保存し、受理レスポンスを受け取ったらすぐにタスク ID を記録してください。

ポーリング、レート制限、保持

プラットフォームはすべての呼び出しグループに対して並行数や API キーごとの照会頻度を一律に公表していません。クライアントは 429 レスポンスに従い、バックオフ付きのポーリングを使用し、5～15 秒に 1 回の照会を推奨します。完成映像が生成されたらできるだけ早くダウンロードまたは転送し、返された URL を恒久的なアドレスとして扱わないでください。タスクがまだ照会可能でも metadata.url の有効期限が切れている場合は、まず元のタスクを再度照会し、リンクを復元できない場合、公開エンドポイントは同じアドレスを再生成できることを保証しません。

冪等性とクライアントリクエスト番号

現在の公開動画エンドポイントは、ユーザーが制御できる公式の冪等フィールドを約束しておらず、カスタムリクエスト番号がリクエスト本文に基づいて重複排除されることも約束していません。呼び出し側は自身の業務リクエスト番号で関連付けを記録できますが、プラットフォームが必ず認識する冪等キーとして扱わないでください。プラットフォーム側では、タスク ID が返された後にのみ信頼できる復元の根拠があります。

API キーの変更

タスクと素材の所属はプラットフォームのアカウントに基づきます。同じアカウントでキーを変更した後も元のタスクを照会でき、タスク作成時のキーで照会を再試行すれば問題ありません。変更後のキーが同じアカウントに属していない場合、照会は 401 または 404 を返します。この場合は照会失敗を回避するためにタスクを再作成しないでください。

課金、失敗、返金

素材の登録、審査、参照動画のダウンロード、動画生成に課金されるかどうかは、現在のモデルとプラットフォームの価格設定によって異なります。動画タスクは完了時に実際の使用量で精算され、作成成功時に事前に課金されることはなく、完了後の請求には実際の課金記録が 1 件だけ現れます。送信前に残高が予測額をカバーするか検証され、不足している場合は読み取り可能なメッセージが直接返され、タスクは作成されません。費用データは精算完了後にのみ照会レスポンスに現れます：

• 作成レスポンスはタスクが受理されたことだけを示し、この時点では精算データがないため課金フィールドは返されません。作成レスポンスから今回の費用を判断しないでください。
• 照会レスポンスはタスク完了・精算後に usage を返します。usage.total_tokens は今回課金対象の動画 token 数（上流は 1 つの token 数のみを報告し、プラットフォームの請求基準で usage.prompt_tokens に記録され、usage.completion_tokens は 0）、usage.quota は消費したクォータ、usage.amount は同じクォータを換算した人民元金額（usage.currency は固定で CNY）です。
• パラメータ検証の失敗（HTTP 400 / 403）はリクエストが受理されなかったことを示し、生成タスクの費用は発生しません。
• タスク ID が返された後、課金されるかどうかと失敗時の返金は、そのモデルとプラットフォームの課金規則に従って処理されます。
• 審査失敗、生成失敗、タスクキャンセルの課金と返金の規則は、タスクのステータスだけから推測することはできません。
• 費用を照合する必要がある場合は、タスク ID、モデル ID、作成日時、API キーの所属アカウントを保存し、照会レスポンスの usage.quota / usage.amount をコンソールの請求と照合するか、プラットフォームサポートに連絡してください。

七、よくあるエラーレスポンス

{
  "error": {
    "code": "invalid_parameter",
    "message": "当前模型不支持参考视频，或参考素材数量超出限制",
    "type": "invalid_request_error",
    "param": "content"
  }
}