Multiple Images and Reference Videos

This page answers API integration questions about "multiple reference images + one reference video", including capability boundaries, ordering rules, depth video, audio, task recovery, and billing. For the complete field table and copyable examples of the request body, see Video Generation API; for adding assets to the library, see Asset Library API.

The Short Answer

• Multiple images and one reference video use the same content array: each image occupies one image_url element, and the video occupies one video_url element.
• "Depth video" has no separate deep_video field; submit it as an ordinary reference video with role set to reference_video.
• The array order is the asset order. Write "image 1, image 2, image 3, reference video" explicitly in the prompt rather than relying on the server to guess the order from file names.
• generate_audio: false means turning off audio output in the generated result; it does not mean preserving the original audio track of the input reference video, nor does it mean copying the input audio into the final video.
• Exact limits on image count, video count, file size, encoding, and concurrency are subject to the model catalog and actual API responses; the platform does not promise one uniform set of limits for all Seedance variants.
• If you must preserve the original clip's motion, camera angles, and cuts, the reference video can only serve as a model reference. The current public request has no general parameter to "force a cut at second N"; exact timing cannot be guaranteed by API fields alone.

1. Confirm Current Model Capabilities

First read the model catalog visible to the current key:

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

The catalog only confirms "whether a model is visible and which APIs it can be used with"; data[].id is the model value to fill in requests. Specific limits such as the number of reference images, reference video, reference audio, output ratio, duration, and resolution are subject to the model details page and the parameter errors returned by the API; the platform will not guess at limits that the catalog does not list.

2. Adding Reference Assets to the Library and Referencing Them

Fictional character design sheets, multi-view character images, and unoccupied scene images are not portrait authorization assets; add them to the library as ordinary virtual assets:

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

After the asset status becomes Active, the image URL in the video request can be changed to:

asset://asset-20260911035115-etexu

When images are added to the library one by one, each gets its own asset_id. Character images and scene images can go in the same virtual group or in separate groups; when submitting a video, reference them through different content elements. For intake, polling, and error responses, see Asset Library API.

On successful submission, status is usually Processing, changing to Active when processing completes; on failure, status is Failed and error_message gives the reason. Review is asynchronous processing, and the platform does not promise a uniform duration for all images; your program should query the same asset_id and must not resubmit while it is Processing.

3. Multiple Images + One Reference Video

The request below expresses "1 character image + 2 scene images + 1 reference video". Array indexes are explained starting from 1:

1. content[1] is image 1, the character image;
2. content[2] is image 2, scene image 1;
3. content[3] is image 3, scene image 2;
4. content[4] is the reference video.

content[0] is the text prompt and is not counted in the image numbering.

{
  "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
}

After successful creation, the task ID is returned; subsequently query only this task:

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

If the response explicitly indicates that the current model does not support the asset library, use a public HTTPS image address that the model supports or switch models; do not bypass asset review. For complete creation and query response examples, see Video Generation API.

4. Boundaries of Reference Video, Audio, and Depth Video

A Reference Video Is Not a Precise Control Track

A grayscale depth video is still an ordinary reference_video in the public API structure. Unless the current model details separately declare depth control capability, the platform will not interpret grayscale values as depth constraints, nor will it guarantee strict reproduction of the original video's depth, motion trajectory, or cuts.

A reference video can help the model understand motion, camera angles, composition, and pacing, but the final video is still regenerated by the model. The current public request has no general timecode track or forced-cut field; when you need a cut close to a certain point in time, you can only describe it in the prompt and check the final video after generation; if frame-level precision is required, it should be done during external editing or compositing.

Input Audio Track and generate_audio

When the reference video has an original audio track, whether the model reads that track depends on the current model's reference video implementation. The definite meaning of generate_audio: false is to turn off audio output in the generated result; it does not promise to copy the input video's audio track, nor does it promise to use the input track as a separate reference audio.

• If the goal is "generate a silent video", you can pass generate_audio: false;
• If the goal is "preserve the original clip's audio", do not rely on this field alone; after downloading the final video, handle it in your own audio-video compositing pipeline, or choose a configuration where the model details explicitly support reference audio and output audio;
• When the model details do not declare support for reference audio, do not submit reference_audio additionally.

5. Limits That Cannot Be Promised Uniformly Today

On "Whether the Current Group Supports This Set of Requests"

A calling group and an asset library group are two different concepts; you cannot judge whether multiple images or reference videos are supported solely from the console group name. The actual order of judgment is:

1. The selected model exists in /v1/models;
2. The model details explicitly allow reference images and reference videos;
3. The referenced asset status is Active;
4. The creation API returns queued, meaning the request has been accepted;
5. If it ultimately failed, read error.code and error.message to determine whether the issue is the combination or the assets.

The platform will not silently switch a model that does not support reference videos to another model, to avoid unpredictable costs and results.

6. Task Recovery, Rate Limiting, Idempotency, and Billing

Querying and Recovery

After the creation API returns an id, you must save it immediately; if the network is interrupted but you already have the task ID, query only the original task. The current public API has no general way to look up a task by "prompt + assets + parameters"; if the connection drops before the creation response returns and you have no task ID, the platform cannot guarantee recovering the original task from the request body alone. Therefore, callers should save business requests in their own database and persist the task ID as soon as the acceptance response is received.

Polling, Rate Limiting, and Retention

The platform does not uniformly publish concurrency and per-API-key query frequency for all calling groups; clients should honor 429 responses and use backoff polling, preferably once every 5–15 seconds. Download or transfer the final video as soon as possible after generation; do not treat the returned URL as a permanent address. If the task is still queryable but metadata.url has expired, query the original task again first; if the link cannot be recovered, the public API does not guarantee regenerating the same address.

Idempotency and Client Request Numbers

The current public video API does not promise an official user-controlled idempotency field, nor does it promise that a custom request number can be deduplicated by request body. Callers can use their own business request number for correlation records, but should not treat it as an idempotency key that the platform will definitely recognize; on the platform side, a reliable basis for recovery exists only after the task ID is returned.

Changing the API Key

Task and asset ownership is based on the platform account; after changing keys within the same account, you can continue to query the original task by retrying with the key used at creation. If the new key does not belong to the same account, queries return 401 or 404; in that case, do not recreate the task to work around the failed query.

Billing, Failures, and Refunds

Whether asset intake, review, reference video download, and video generation are billed depends on the current model and the platform's pricing configuration. Video tasks are settled at completion based on actual usage; a successful creation does not deduct fees in advance, and after completion only one actual charge record appears on the bill. Before submission, the platform verifies whether the balance covers the estimate; if insufficient, it returns a readable message directly and does not create the task. Cost data appears in query responses only after settlement is complete:

• Creation responses only mean the task has been accepted; there is no settlement data at this point, so no billing fields are returned; do not judge the cost of this request from the creation response;
• Query responses return usage after the task completes settlement: usage.total_tokens is the number of video tokens billed for this request (the upstream reports only one token count, which is recorded under usage.prompt_tokens according to the platform's billing convention, with usage.completion_tokens being 0); usage.quota is the credits consumed; usage.amount is the RMB amount converted from the same credits (usage.currency is fixed to CNY);
• Parameter validation failures (HTTP 400 / 403) mean the request was not accepted and will not incur generation task costs;
• Once a task ID has been returned, whether and how much to charge, and failure refunds, are handled according to that model's and the platform's billing rules;
• The charging and refund rules for review failures, generation failures, and cancelled tasks cannot be inferred from task status alone;
• To verify costs, save the task ID, model ID, creation time, and the account that owns the API key, then check usage.quota / usage.amount from the query response against the console bill, or contact platform support.

7. Common Error Responses

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