Seedance 真人素材视频生成完整教程

使用真人素材请使用SD分组

1. 流程与调用前准备

真人素材建议采用可复用、可追踪的素材库流程：上传真人图片 → 发起审核 → 查询素材直到 active → 使用 asset:// 引用创建视频 → 查询视频直到 succeeded → 读取 content.video_url 下载结果。选择素材库方式的每张图片都要分别完成上传和审核。直接传入 URL/base64 的方式及边界见 1.1 和 4.4 节。

本文描述本站统一接口。客户端只需要本站 Base URL、API 令牌和模型名称；素材服务由令牌对应的分组自动选择。使用前在模型广场确认模型支持 /v1/videos，令牌有对应模型权限、可用额度，且分组已开通真人素材能力。首次接入和需要稳定复用素材的业务，建议使用固定单分组令牌。

Seedance 官方说明介绍了模型的多模态能力；本文接口以本站实现为准。示例使用 doubao-seedance-2-0-260128，实际可用模型以当前令牌及模型广场为准。上传和审核不需要指定生成模型。

准备 Bash、curl、jq 和有权使用的真人照片。BASE_URL 填站点根地址，不要重复附加 /v1。在自己的终端设置环境变量，密钥不要写入公开代码：

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="替换为你的本站 API 令牌"
export MODEL="doubao-seedance-2-0-260128"

1.1 已审核素材与原始图片如何区分

保留相同的 type=image_url，通过 image_url.url 的前缀区分输入来源，通过 role 区分图片用途。 不需要添加真人标记，也不能由调用方声明某张图片已审核通过。

已审核真人素材作为参考图时：

Copy{"type": "image_url", "role": "reference_image", "image_url": {"url": "asset://0123456789abcdef0123456789abcdef"}}

普通场景图片作为参考图时：

Copy{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://media.example.com/scene.jpg"}}

两者的 role 相同，是因为都用作参考图；前缀不同，服务端处理路径就不同。asset:// 后面必须是本站上传返回的素材 ID，不能填写上游 UUID，也不能把图片地址改成这个前缀来声明审核通过。上传刚返回的引用可能仍是 pending，必须等到 active 才能生成。

输入来源不等于是否包含真人。 已审核的非真人图片也可使用 asset://；HTTP(S)/base64 图片也可能包含真人。真人素材应通过素材库显式上传、审核到 active，再复用返回的引用；直传图片不调用审核，误传真人图片被上游拒绝时返回上游错误。

生成模式与审核状态独立。 role=reference_image 默认选择 referToVideo；单图驱动画面时使用 role=first_frame 并显式指定顶层 refer_model=imageToVideo。两种用途都能使用已审核素材，不能用模式名称区分真人与非真人。首尾帧和其他模式见 4.2 节。

2. 接口与参数速查

所有接口使用 Authorization: Bearer $API_KEY。只有上传使用 multipart/form-data，curl 的 -F 会自动设置 boundary，不要手动写上传的 Content-Type。

🆕 本次补充： 上传只需传入 file，每次一个图片、音频或视频文件；多个参考素材需要多次调用。

🆕 本次补充： 图片和音频上传后，将返回的素材 ID 放入 compliance 请求路径主动发起审核，无需请求体。视频上传成功后会自动发起审核，不要重复调用 compliance；保存返回的素材 ID 并查询到 active。音频也可以在生成请求中直接提供 HTTP(S) URL 或 MP3/WAV data URI。

3. 上传图片并发起审核

Copycurl --fail-with-body --silent --show-error --max-time 180 \
  "$BASE_URL/v1/seedance/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./portrait.jpg"

上传响应的关键字段如下，示例 ID 为虚构值。先判断 success，再读取 data.id 和 data.reference：

Copy{
  "success": true,
  "message": "",
  "data": {
    "id": "0123456789abcdef0123456789abcdef",
    "reference": "asset://0123456789abcdef0123456789abcdef",
    "asset_type": "image",
    "status": "pending",
    "error_message": "",
    "compliance_started": false,
    "review_task_id": "",
    "retry_after": 5,
    "created_at": 1800000000,
    "updated_at": 1800000000,
    "last_polled_at": 0
  }
}

将上传返回的 data.id 放入路径，主动启动审核。{id} 只填 ID，不带 asset:// 前缀：

Copyexport ASSET_ID="替换为上传返回的 data.id"
curl --fail-with-body --silent --show-error --max-time 180 \
  -X POST "$BASE_URL/v1/seedance/assets/$ASSET_ID/compliance" \
  -H "Authorization: Bearer $API_KEY"

curl --fail-with-body --silent --show-error --max-time 60 \
  "$BASE_URL/v1/seedance/assets/$ASSET_ID" \
  -H "Authorization: Bearer $API_KEY"

发起审核和查询返回相同的素材结构。审核开始后 compliance_started=true，review_task_id 可用于在任务日志中定位记录。服务端后台继续审核，客户端断开后可用原素材 ID 恢复查询，无需重复上传。

素材接口可能返回 HTTP 200 但 success=false，例如 {"success":false,"message":"当前令牌未配置可用素材适配器"}。curl --fail-with-body 只能拦截 HTTP 错误，业务代码还必须检查 success。对 pending 只轮询 GET，不要反复 POST 审核。

3.1 真人照片在远程 URL 上时

如果照片只有网络地址，先下载为本地文件，再按本节上传和审核。下载图片时不携带本站 API 令牌：

Copyexport IMAGE_URL="https://media.example.com/portrait.jpg"
curl --fail-with-body --silent --show-error --location \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 15 --max-time 120 --max-filesize 31457280 \
  "$IMAGE_URL" --output ./portrait.jpg

替换为自己的图片直链，确认下载成功后，使用第 3 节的 -F "file=@./portrait.jpg" 上传，再发起审核。上传接口接收文件内容，不能把图片 URL 当作 file 字段的值。

Copycurl --fail-with-body --silent --show-error --max-time 180 \
  "$BASE_URL/v1/seedance/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./reference.mp4"

Copy{
  "success": true,
  "message": "",
  "data": {
    "id": "0123456789abcdef0123456789abcdef",
    "reference": "asset://0123456789abcdef0123456789abcdef",
    "asset_type": "video",
    "status": "pending",
    "compliance_started": true,
    "review_task_id": "task_example_review",
    "retry_after": 5
  }
}

Copyexport VIDEO_ASSET_ID="替换为上传响应的 data.id"
curl --fail-with-body --silent --show-error --max-time 60 \
  "$BASE_URL/v1/seedance/assets/$VIDEO_ASSET_ID" \
  -H "Authorization: Bearer $API_KEY"

Copy{"type":"video_url","role":"reference_video","video_url":{"url":"asset://替换为已通过审核的视频素材ID"}}

4. 使用审核通过的素材生成视频

图片 URL 字段直接使用状态为 active 的素材响应中的 reference。以下示例将人物作为参考图，显式使用 refer_model=referToVideo；如果需要单图驱动的 imageToVideo，按 1.1 和 4.2 节选择用途。真人图片无需更换专用视频端点：

Copyexport ASSET_REFERENCE="asset://替换为已通过审核的素材ID"
jq -n --arg model "$MODEL" --arg ref "$ASSET_REFERENCE" '{
  model: $model,
  content: [
    {type: "text", text: "参考图中的人物自然看向镜头，用中文说：大家好，很高兴认识你，希望我们一起发现更多精彩。保持人物外貌和服装一致，口型自然。"},
    {type: "image_url", role: "reference_image", image_url: {url: $ref}}
  ],
  refer_model: "referToVideo",
  duration: 8,
  ratio: "9:16",
  resolution: "720P",
  generate_audio: true
}' > video-request.json

curl --fail-with-body --silent --show-error --max-time 180 \
  "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @video-request.json

使用素材库引用时，必须先完成该素材的上传和审核，且 audio_url 只能引用音频素材、image_url 只能引用图片素材。直接传入原始图片的流程、限制与日志差异见 4.4 节。

Copyexport ASSET_REFERENCE="asset://替换为已通过审核的素材ID"
jq -n --arg model "$MODEL" --arg ref "$ASSET_REFERENCE" '{
  model: $model,
  content: [
    {type: "text", text: "参考素材中的人物自然看向镜头并挥手，保持人物外貌和服装一致。"},
    {type: "image_url", role: "reference_image", image_url: {url: $ref}}
  ],
  refer_model: "referToVideo",
  duration: 8,
  ratio: "9:16",
  resolution: "720P",
  generate_audio: true
}' | curl --fail-with-body --silent --show-error --max-time 180 \
  "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

Copy{
  "id": "task_example_video",
  "task_id": "task_example_video"
}

Copyexport TASK_ID="替换为创建响应的 id 或 task_id"
curl --fail-with-body --silent --show-error --max-time 60 \
  "$BASE_URL/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Copy{
  "id": "task_example_video",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "created_at": 1800000000,
  "updated_at": 1800000042,
  "content": {
    "video_url": "https://media.example.com/generated.mp4"
  }
}

4.1.1 /v1/videos 兼容入口参数

生成参数放在 JSON 顶层，参考素材放在 content。除上表的常用参数外，还可以指定提示词、参考模式和输出格式：

Seedance 2.5 Draft 模式

Draft 模式分两步执行。第一步设置 draft: true，只支持 resolution: "480p"（省略时按 480p 处理）。确认样片后，第二步的 content 必须且只能包含一个 draft_task：

Copy{
  "model": "doubao-seedance-2-5-260628",
  "content": [{"type": "draft_task", "draft_task": {"id": "<DRAFT_TASK_ID>"}}],
  "resolution": "1080p"
}

第二步必须显式使用 1080p，模型必须与样片一致；提示词、素材、时长、比例、seed 和音频设置由样片任务继承。两个步骤独立计费，分别按实际任务的分辨率和输入视频事实结算。

新接入推荐使用 POST /api/v3/contents/generations/tasks，旧客户端可继续使用兼容入口 POST /v1/videos；查询分别对应 /api/v3/contents/generations/tasks/{task_id} 和 /v1/videos/{task_id}。两个入口返回的都是网关 task ID，draft_task.id 同时兼容网关 task ID 和同一用户对应的上游 task ID。

示例：顶层 prompt 的纯文本写法。填写第 1 节的环境变量后可直接调用，不需要上传图片：

Copyjq -n --arg model "$MODEL" '{
  model: $model,
  prompt: "海边清晨，镜头缓慢推进，保持无字幕。",
  resolution: "720P",
  ratio: "16:9",
  duration: 8,
  refer_model: "textToVideo",
  generate_audio: false,
  count: 1
}' | curl --fail-with-body --silent --show-error --max-time 180 \
  "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

4.2 参考模式与分辨率范围

模式值区分大小写。省略模式时：无素材为文生视频；单张无参考角色的图片为图生视频；两张无参考角色的图片为首尾帧；带 reference_* 角色或音视频素材时为参考生成。多参考图建议显式使用 refer_model=referToVideo 和 role=reference_image。

视频延展必须显式设置 refer_model=videoExtend；单段视频配合 role=reference_video 并不会自动选择延展。上游提供的 videoEdit 和 count=2/4 尚未接入本站；本站当前只支持 count=1。

分辨率和画幅按所选模型填写：

默认分辨率为 720P；默认画幅在 2.0 系列为 16:9，2.5 为 adaptive。高分辨率和超分辨率需所在分组开通支持。

4.3 2.5 单图、首尾帧与输出格式示例

以下 JSON 展示单张真人图片、无音频、MOV 输出的组合。同分组、素材服务配置未变更时，可复用前面已审核的素材；生成前确认令牌有目标模型权限。

Copy{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "参考图中的人物自然微笑并向镜头挥手，保持外貌一致。",
  "content": [
    {"type": "image_url", "role": "first_frame", "image_url": {"url": "asset://0123456789abcdef0123456789abcdef"}}
  ],
  "refer_model": "imageToVideo",
  "resolution": "720P",
  "ratio": "adaptive",
  "duration": 8,
  "generate_audio": false,
  "output_format": "mov",
  "count": 1
}

首尾帧则用以下请求，按数组顺序放首帧和尾帧，两张都要完成审核：

Copy{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "从首帧自然过渡到尾帧，保持人物身份与服装一致。",
  "content": [
    {"type": "image_url", "role": "first_frame", "image_url": {"url": "asset://0123456789abcdef0123456789abcdef"}},
    {"type": "image_url", "role": "last_frame", "image_url": {"url": "asset://fedcba9876543210fedcba9876543210"}}
  ],
  "refer_model": "firstAndLastFrame",
  "resolution": "720P",
  "ratio": "adaptive",
  "duration": 8,
  "generate_audio": false,
  "output_format": "mp4",
  "count": 1
}

将任一 JSON 保存为 video-request.json 后，使用第 4 节的 curl --data-binary @video-request.json 提交，再用第 5 节查询和下载；MOV 输出保存为 .mov。不要把所有示例参数机械合并，也不要把输出格式字段用于 2.0 系列。

4.4 普通图片 URL 与混合引用

image_url.url 也支持普通 HTTP(S) 图片直链。以下是直接传 URL 的完整调用示例；请替换为服务端可以直接下载的图片文件地址：

Copyexport IMAGE_URL="https://media.example.com/scene.jpg"
jq -n --arg model "$MODEL" --arg image "$IMAGE_URL" '{
  model: $model,
  content: [
    {type: "text", text: "参考图片中的场景，镜头缓慢推进，保持自然光影。"},
    {type: "image_url", role: "reference_image", image_url: {url: $image}}
  ],
  duration: 8,
  ratio: "16:9",
  resolution: "720P",
  generate_audio: true
}' | curl --fail-with-body --silent --show-error --max-time 180 \
  "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

普通图片直传不调用合规审核。 网关流式下载或解码并上传图片，使用上传返回的 UUID 提交生成，不调用 /openapi/assetLibrary/compliance/check，也不等待审核状态。URL/base64 只是输入来源，不能据此判断图片是否包含真人；真人图片请先通过素材库审核，再使用 asset://。如果误传真人图片导致上游拒绝，接口返回上游错误；异步拒绝会出现在视频任务失败原因中。

直传方式不会创建本站素材记录或 review_task_id，没有独立的“素材审核”任务，也不会在本次请求超时后后台续接。需要复用素材、等待较长审核或保留审核记录时，按第 3 节显式上传并审核，再使用 asset://。保留 Request-ID，检查提交错误或异步任务失败原因；创建视频返回成功只代表任务已受理，仍需查询到 completed。

如果素材下载、类型校验、上传或请求体构建失败，视频任务可能尚未创建，但网关仍会写入一条零额度错误使用日志。使用 /log/get-request?id=<Request-ID> 可查询脱敏后的具体原因；这类失败不会产生视频计费。

下面是直接提交图片 data URI 的完整 JSON。示例中的 iVBORw0KGgo... 仅表示一张标准 PNG 的 Base64 内容，实际请求必须替换为完整编码：

Copy{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "保持参考图主体完整，只做轻微镜头推进和自然光影变化。"},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}
  ],
  "duration": 4,
  "ratio": "16:9",
  "resolution": "480P",
  "generate_audio": false
}

只接受带 MIME 前缀的图片 data URI：data:image/png;base64,...、data:image/jpeg;base64,... 等；音频参考支持 data:audio/mpeg;base64,... 和 data:audio/wav;base64,...。裸 Base64（没有对应的 data:<mime>;base64, 前缀）以及 data:video/... 均不支持。网关流式解码并直接上传，不把解码结果落盘；解码后的单张图片最多 30 MiB，单个音频最多 15 MiB，同时受 MAX_FILE_DOWNLOAD_MB、单请求远程素材总预算和 /v1/videos 入口请求体上限约束。Base64 编码本身会增大入口请求体，因此小于上述解码限制的内容也可能先触发入口体积限制。

同一次请求中，可以将已审核的人物素材和普通场景图片 URL 组合使用。下面 JSON 作为第 4 节的请求体：人物引用复用已审核 UUID，场景 URL 上传并检查到 ACTIVE 后使用其 UUID；上游仍可能在提交或生成阶段拒绝素材。

Copy{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "第一张图中的人物在第二张图的场景中自然行走，保持人物外貌一致。"},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "asset://0123456789abcdef0123456789abcdef"}},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://media.example.com/scene.jpg"}}
  ],
  "duration": 8,
  "ratio": "16:9",
  "resolution": "720P",
  "generate_audio": true
}

URL 不能是网页地址、Markdown 链接或需要登录的地址；不能携带本站 API 令牌。顶层 image、images、images_url、input_reference 和 content[].image_url.url 的图片值都走同一条处理路径。请确保链接在请求处理期间有效，且符合站点下载策略和 30 MiB 单图限制；data URI 则还要预留 Base64 编码带来的请求体开销。提交成功后的任务查询与下载仍按第 5 节操作。

4.5 Seedance 2.5 视频延展

使用已有视频继续创作时，选择 Seedance 2.5 并显式传入 refer_model=videoExtend。先设置第 1 节的 BASE_URL、API_KEY，再将 VIDEO_URL 替换为服务端可直接下载的 HTTPS 视频文件地址：

Copyexport VIDEO_URL="https://media.example.com/source.mp4"
jq -n --arg video "$VIDEO_URL" '{
  model: "doubao-seedance-2-5-260628",
  content: [
    {type: "text", text: "延续视频中的场景和主体动作，镜头平稳推进，保持画面风格一致。"},
    {type: "video_url", role: "reference_video", video_url: {url: $video}}
  ],
  refer_model: "videoExtend",
  ratio: "adaptive",
  duration: 5,
  resolution: "480P",
  generate_audio: false,
  output_format: "mp4",
  count: 1
}' | curl --fail-with-body --silent --show-error --max-time 180 \
  "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

本站要求此模式的视频数量恰好为 1、ratio=adaptive，duration 为 4–30 秒；负数（包括 -1）会被拒绝。示例中的 duration=5 是本次生成参数，不据此承诺结果已将原视频和新增内容拼接。图片素材 asset://、裸 Base64 和视频 data URI 均不能作为延展视频输入。省略 refer_model 时仍按 referToVideo 处理。

下表是上游对输入视频的要求，不代表网关已经在本地逐项探测并校验媒体属性：

实际可下载大小还受站点 MAX_FILE_DOWNLOAD_MB 和单请求素材总预算限制，站点配置可能小于 200 MiB。提交成功后，保存返回的 id 或 task_id，按第 5 节查询到 completed 后下载；提交受理不代表生成已经完成。

5. 查询生成任务并下载

视频响应与素材响应不同：视频字段位于顶层，没有 data 包装。创建响应示例：

Copy{
  "id": "task_example_video",
  "task_id": "task_example_video",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 0
}

Copyexport VIDEO_TASK_ID="替换为创建响应的 id 或 task_id"
curl --fail-with-body --silent --show-error --max-time 60 \
  "$BASE_URL/v1/videos/$VIDEO_TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

queued 表示排队，in_progress 表示生成中，completed 表示成功，failed 表示失败。progress 为进度值，不能单独当作成功依据。初次提交响应的 created_at 可能为 0，后续查询以持久化任务信息为准。完成时可取得 video_url、completed_at 等字段；失败时检查响应中的 error（若返回）及任务日志。审核的 active、任务日志的 SUCCESS 和视频 API 的 completed 属于不同状态体系。

只在 completed 后下载，保存到文件而不是把二进制输出到终端：

Copycurl --fail-with-body --silent --show-error --location \
  --max-time 300 --max-filesize 536870912 \
  "$BASE_URL/v1/videos/$VIDEO_TASK_ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  --output self-introduction.mp4

也可下载响应中的 video_url；下载外部媒体地址时不要附加本站 API 令牌。结果地址可能过期，请及时保存。创建请求超时不等于任务未受理，应先查看任务日志或已保存的任务 ID，避免重复提交及重复费用。

6. 可直接执行的单图与多图完整脚本

下面脚本串起上传、审核、生成、查询和下载，默认使用当前目录的 portrait.jpg。如需多图，把 IMAGES 改为多个文件路径；脚本逐张上传，全部通过审核后仅提交一次视频任务。先设置第 1 节的三个环境变量；脚本输出的 JSON 是业务记录，包含素材 ID、审核任务 ID 和视频任务 ID，应放在私有目录。

Copy#!/usr/bin/env bash
set -euo pipefail
umask 077
: "${BASE_URL:?Set BASE_URL first}"
: "${API_KEY:?Set API_KEY first}"
: "${MODEL:?Set MODEL first}"
BASE_URL="${BASE_URL%/}"
IMAGES=("./portrait.jpg")
# Multiple references: IMAGES=("./front.jpg" "./side.jpg")
for image in "${IMAGES[@]}"; do test -f "$image"; done
WORK_DIR=$(mktemp -d "./seedance-run.XXXXXX")
printf 'Records: %s\n' "$WORK_DIR"

api() {
  curl --fail-with-body --silent --show-error \
    --connect-timeout 15 --max-time 180 \
    -H "Authorization: Bearer $API_KEY" "$@"
}
asset_ok() {
  jq -e '.success == true and (.data | type == "object")' "$1" >/dev/null || {
    jq '{success, message}' "$1" >&2
    return 1
  }
}
printf '[]\n' > "$WORK_DIR/references.json"
index=0
for image in "${IMAGES[@]}"; do
  index=$((index + 1))
  record="$WORK_DIR/asset-$index.json"
  api "$BASE_URL/v1/seedance/assets" \
    -F "file=@$image" > "$record"
  asset_ok "$record"
  asset_id=$(jq -er '.data.id | select(type == "string" and length > 0)' "$record")
  printf 'Asset: %s\n' "$asset_id"
  api -X POST "$BASE_URL/v1/seedance/assets/$asset_id/compliance" \
    > "$WORK_DIR/review-$index.json"
  asset_ok "$WORK_DIR/review-$index.json"
  jq -r '.data.review_task_id' "$WORK_DIR/review-$index.json"
  deadline=$((SECONDS + 1800))
  while true; do
    api "$BASE_URL/v1/seedance/assets/$asset_id" > "$record"
    asset_ok "$record"
    state=$(jq -r '.data.status' "$record")
    case "$state" in
      active) break ;;
      failed|deleted) jq '.data | {id, status, error_message, review_task_id}' "$record" >&2; exit 1 ;;
      pending) ;;
      *) printf 'Unknown asset state: %s\n' "$state" >&2; exit 1 ;;
    esac
    if (( SECONDS >= deadline )); then
      printf 'Review wait timed out; resume GET for %s\n' "$asset_id" >&2
      exit 1
    fi
    sleep $((5 + RANDOM % 3))
  done
  reference=$(jq -er '.data.reference' "$record")
  jq --arg ref "$reference" '. + [$ref]' "$WORK_DIR/references.json" \
    > "$WORK_DIR/references.next.json"
  mv "$WORK_DIR/references.next.json" "$WORK_DIR/references.json"
done

jq -n --arg model "$MODEL" --slurpfile refs "$WORK_DIR/references.json" '{
  model: $model,
  content: ([{type: "text", text: "参考图中的同一人物自然看向镜头，用中文说：大家好，很高兴认识你，希望我们一起发现更多精彩。保持外貌和服装一致，口型自然。"}]
    + ($refs[0] | map({type: "image_url", role: "reference_image", image_url: {url: .}}))),
  duration: 8, ratio: "9:16", resolution: "720P", generate_audio: true
}' > "$WORK_DIR/video-request.json"
api "$BASE_URL/v1/videos" -H "Content-Type: application/json" \
  --data-binary "@$WORK_DIR/video-request.json" > "$WORK_DIR/video-submit.json"
task_id=$(jq -er 'select(.error == null and .success != false) | (.id // .task_id) | select(type == "string" and length > 0)' "$WORK_DIR/video-submit.json")
printf 'Video task: %s\n' "$task_id"
deadline=$((SECONDS + 1800))
while true; do
  api "$BASE_URL/v1/videos/$task_id" > "$WORK_DIR/video-status.json"
  state=$(jq -er 'select(.error == null or .status == "failed") | .status' "$WORK_DIR/video-status.json")
  case "$state" in
    completed) break ;;
    failed) jq '{id, status, error}' "$WORK_DIR/video-status.json" >&2; exit 1 ;;
    queued|in_progress) ;;
    *) printf 'Unknown video state: %s\n' "$state" >&2; exit 1 ;;
  esac
  if (( SECONDS >= deadline )); then
    printf 'Video wait timed out; resume GET for %s\n' "$task_id" >&2
    exit 1
  fi
  sleep $((5 + RANDOM % 6))
done
api --location --max-time 300 --max-filesize 536870912 \
  "$BASE_URL/v1/videos/$task_id/content" \
  --output "$WORK_DIR/video.mp4.part"
mv "$WORK_DIR/video.mp4.part" "$WORK_DIR/video.mp4"
printf 'Completed: %s/video.mp4\n' "$WORK_DIR"

脚本遇到 HTTP 错误、业务错误、审核失败或超时会停止，不会自动重发创建请求。脚本的 30 分钟等待上限只是客户端策略，不是完成时限承诺；超时后保留记录，用原 ID 继续查询。遇到 429 按 Retry-After 等待，恢复 GET 查询，不要为了恢复进度从头运行上传和生成。

7. 多图与音视频混合参考

通过素材库上传并发起审核的每张图片都有独立的 id、reference 和 review_task_id；直接传 URL/base64 不返回这些本地标识。两张参考图也要显式写 role=reference_image：省略 role 时，当前接入可能把两张图片识别为首尾帧。提示词中说明“第一张图用于人物、第二张图用于服装或场景”；多人物时明确各自的位置与动作，避免描述冲突。

本流程当前对 Seedance 2.0 接入最多接受 9 张图、3 段视频、3 段音频；2.5 接入分别为 30、10、10。实际组合还受模型、文件大小及分组能力约束，这些上限不是任意组合均能成功的保证。

参考视频使用 MP4 或 MOV，音频使用 MP3 或 WAV。单张图片最多 30 MiB，2.0 Mini 的参考图片合计不超过 64 MiB；参考音频最多 15 MiB。2.0 系列单段参考视频最多 50 MiB，2.5 最多 200 MiB，还受站点下载上限约束。同一请求的远程素材默认累计上限为 200 MiB；已审核的 asset:// 图片不占这项下载预算。请使用符合目标模型要求的图片尺寸、视频帧率及媒体时长。

保留两张已审核图片，并追加视频和音频参考时，请求结构如下。示例地址和素材 ID 均须替换；纯图片场景直接删除两个音视频项。URL 应是媒体文件地址，不能是网页地址或 Markdown 链接：

Copy{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "以第一张图的人物为主角，参考第二张图的服装与场景，参考视频的舞蹈动作及音频节奏，人物在舞台中央自然跳舞，镜头缓慢推进。"},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "asset://0123456789abcdef0123456789abcdef"}},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "asset://fedcba9876543210fedcba9876543210"}},
    {"type": "video_url", "role": "reference_video", "video_url": {"url": "https://media.example.com/dance.mp4"}},
    {"type": "audio_url", "role": "reference_audio", "audio_url": {"url": "https://media.example.com/music.mp3"}}
  ],
  "duration": 8,
  "ratio": "16:9",
  "resolution": "720P",
  "generate_audio": true
}

将此 JSON 作为 POST /v1/videos 请求体，之后仍按第 5 节查询。generate_audio=true 是输出音轨开关，不要求提供参考音频，也不保证精确复刻音色。

8. 素材列表、复用与删除

Copycurl --fail-with-body --silent --show-error --get \
  "$BASE_URL/v1/seedance/assets" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "status=active" \
  --data-urlencode "page=1" --data-urlencode "size=20"

# Delete only when this reference is no longer needed.
curl --fail-with-body --silent --show-error \
  -X DELETE "$BASE_URL/v1/seedance/assets/$ASSET_ID" \
  -H "Authorization: Bearer $API_KEY"

列表返回 data.items、data.total、data.page 和 data.size。素材对象结构与详情一致。删除成功返回 {"success":true,"message":"","data":{"id":"素材ID","status":"deleted"}}；删除不代表已生成的视频被取消或所有外部存储副本被物理清除。

素材属于上传账户，并受当前令牌的分组权限限制。已审核素材可跨该分组支持的 Seedance 型号复用，生成时校验目标模型权限。素材绑定分组必须等于本次生成最终选择的分组；多分组令牌建议改用固定单分组令牌，以便稳定复用。素材服务配置更换或权限撤销后，可能需要重新上传审核。

9. 审核日志、素材 UUID 与错误排查

🆕 本次补充： 图片或音频主动发起审核、或者视频上传后自动发起审核时，打开任务日志，在类型筛选中选择“素材审核”，在任务 ID 筛选中填写素材响应的 review_task_id，即可定位对应审核记录。直接传 URL/base64 不调用审核，因此没有独立审核任务；请保留生成请求的 Request-ID，以及成功受理后的视频任务 ID，通过提交错误或视频任务失败原因排查上游拒绝。

任务日志中的“素材审核”记录会保存审核任务 ID、状态、模型、素材 ID 和 asset:// 引用。管理员诊断可查看上游素材 UUID 及审核状态；普通调用方只需持久化以下关联：业务记录 → 素材 id/reference → review_task_id → 视频 id/task_id。不要用审核任务 ID 调用视频查询接口，也不要把管理员诊断中的上游 UUID 拼成本站素材引用。

遇到不确定的提交结果，优先查询已有任务，记录响应中的 Request-ID 供排查。图片审核通过只代表素材可用，视频提示词和生成结果仍可能审核失败。更多异步处理和错误说明见视频任务 API、异步任务指南和排障指南。