多图与参考视频说明

本页回答「多张参考图 + 一个参考视频」的程序接入问题，包括能力边界、顺序规则、深度视频、音频、任务恢复和计费。请求体的完整字段表和可复制示例见视频生成接口，素材入库见素材库接口。

先看结论

• 多张图片和一个参考视频使用同一个 content 数组：每张图片占一个 image_url 元素，视频占一个 video_url 元素。
• 「深度视频」没有单独的 deep_video 字段，按普通参考视频提交，role 使用 reference_video。
• 数组顺序就是素材顺序。建议在提示词里明确写「图片1、图片2、图片3、参考视频」，不要依赖服务端按文件名猜顺序。
• generate_audio: false 表示关闭生成结果的音频输出，它不等于保留输入参考视频的原声音轨，也不等于把输入音频复制到成片。
• 精确的图片数量、视频数量、文件大小、编码和并发上限以模型目录和实际接口响应为准，平台没有为所有 Seedance 变体承诺一套统一上限。
• 如果必须保留原片的动作、机位和切镜，参考视频只能作为模型参考。当前公开请求没有「在第 N 秒强制切镜」的通用参数，精确时序不能仅靠接口字段保证。

一、确认当前模型能力

先读取当前 Key 可见的模型目录：

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

目录只确认「模型是否可见、可用于哪些接口」，data[].id 才是请求时要填的 model。参考图片数量、参考视频、参考音频、输出比例、时长和清晰度等具体限制，以模型详情页和接口返回的参数错误为准；目录没有列出的限制，平台不会替模型猜测。

二、参考素材的入库与引用

虚构人物设定图、角色多视图和无人场景图都不是真人授权素材，按普通虚拟素材入库：

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

素材状态变成 Active 后，视频请求里的图片 URL 可以改成：

asset://asset-20260911035115-etexu

图片逐张入库时，每一张都会得到独立的 asset_id。人物图和场景图可以放在同一虚拟分组，也可以分别建立分组；提交视频时通过不同的 content 元素引用。入库、轮询和错误响应见素材库接口。

提交成功时 status 通常是 Processing，处理完成后变成 Active；失败时 status 为 Failed、error_message 给出原因。审核是异步处理，平台不对所有图片承诺统一时长，程序应查询同一个 asset_id，不要在 Processing 时重复提交。

三、多图 + 一个参考视频

下面的请求表达「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。

五、当前不能统一承诺的限制

关于「当前分组是否支持这组请求」

调用分组和素材库分组是两个概念，不能仅凭控制台分组名称判断是否支持多图或参考视频。实际判断顺序是：

1. /v1/models 中选定模型存在；
2. 模型详情明确允许参考图和参考视频；
3. 引用素材状态为 Active；
4. 创建接口返回 queued，说明请求已受理；
5. 若最终 failed，读取 error.code 和 error.message 判断组合或素材问题。

平台不会把一个不支持参考视频的模型静默切换到另一个模型，以免产生不可预期的费用和结果。

六、任务恢复、限流、幂等和计费

查询和恢复

创建接口返回 id 后必须立即保存，网络中断但已经拿到任务 ID 时只查询原任务。当前公开接口没有按「提示词 + 素材 + 参数」反查任务的通用方式；如果连接在创建响应返回前中断且没有任务 ID，平台无法保证仅凭请求正文找回原任务。因此调用方应在自己的数据库里保存业务请求，并在收到受理响应后立即落库任务 ID。

轮询、限流和保留

平台没有对所有调用分组统一公布并发数和每个 API Key 的查询频率，客户端应遵循 429 响应并使用退避轮询，建议 5～15 秒查询一次。成片生成后应尽快下载或转存，不能把返回 URL 当作永久地址；如果任务仍可查询但 metadata.url 已过期，先再次查询原任务，链接无法恢复时公开接口不保证能重新生成同一个地址。

幂等与客户端请求号

当前公开视频接口没有承诺用户可控制的官方幂等字段，也不承诺自定义请求号可以按请求正文去重。调用方可以用自己的业务请求号记录关联，但不要把它当作平台一定会识别的幂等键；平台侧只有在返回任务 ID 后才有可靠的恢复依据。

更换 API Key

任务和素材的归属以平台账号为准，同一账号下更换 Key 后可以继续查询原任务，使用创建任务时的 Key 重试查询即可。如果更换后的 Key 不属于同一账号，查询会返回 401 或 404，此时不要重新创建任务来规避查询失败。

计费、失败和退款

素材入库、审核、参考视频下载和视频生成是否计费，取决于当前模型和平台价格配置。视频任务在完成时按实际用量结算，创建成功不会预先扣费，完成后账单只出现一条实际扣费记录；提交前会校验余额是否覆盖预估，不足时直接返回可读提示且不创建任务。费用数据只在结算完成后出现在查询响应里：

• 创建响应只代表任务已被受理，此时没有任何结算数据，因此不返回扣费字段，不要按创建响应判断本次费用；
• 查询响应在任务完成结算后返回 usage：usage.total_tokens 是本次计费的视频 token 数（上游只上报一个 token 数，按平台账单口径记在 usage.prompt_tokens，usage.completion_tokens 为 0），usage.quota 是消耗的积分，usage.amount 是同一积分折算的人民币金额（usage.currency 固定为 CNY）；
• 参数校验失败（HTTP 400 / 403）表示请求未被受理，不会产生生成任务费用；
• 已返回任务 ID 后，是否收费和失败退款按该模型与平台计费规则处理；
• 审核失败、生成失败、取消任务的扣费和退款规则不能仅由任务状态推断；
• 需要核对费用时，保存任务 ID、模型 ID、创建时间和 API Key 所属账号，用查询响应的 usage.quota / usage.amount 在控制台账单核对，或联系平台支持。

七、常见错误响应

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