Use Reference Image 1 only for the fictional man's face, short wavy dark hair, navy wool coat, gray scarf, and body proportions. Use Reference Video 1 only for the single turn-and-catch motion, natural weight shift, cloth timing, and slow waist-height camera movement; do not copy the woman, her clothing, or the train platform. Use Reference Audio 1 only for rain intensity and action timing. Create one continuous five-second shot in a quiet covered ferry walkway at night. The man stands alone holding one plain cream envelope in his right hand. A brief gust loosens the envelope; he turns once, catches it against his chest, then becomes still. Preserve his referenced identity and outfit throughout. Synchronized audio: soft rain on the roof, one paper flutter, and distant water ambience. No cuts, no extra people, no dialogue, no writing on the envelope, no readable text, no logos, no products, no advertising, no watermark.
Seedance 2.5 Reference-to-Video API
bytedance/seedance-2.5/reference-to-videoSeedance 2.5(Reference-to-Video)可根据提示词和图片、视频、可选音频参考生成最长 30 秒的音画同步视频。为每份素材指定明确用途后,可将人物、构图、视觉风格、动作、运镜、节奏或声音带入新场景,单次最多使用 50 份参考素材。
输入
请至少添加一张参考图片或一个参考视频,音频不能单独提交。
输出
等待运行生成的视频会显示在这里
设置必填输入、分辨率和时长,然后运行任务。
继续使用
示例
REST API
快速开始
配置认证后提交 input 对象,再使用 task_id 查询视频生成结果。
连接 Vidgo API
创建 API Key,将其安全保存在服务端,并通过 Authorization: Bearer VIDGO_API_KEY 请求头发送。
- 端点
- POST
https://api.vidgo.ai/api/generate/submit - 认证
- Authorization: Bearer VIDGO_API_KEY
提交一个生成任务
使用当前模式的最小有效 payload 提交任务。成功后会立即返回 task_id,无需等待视频生成完成。
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "seedance-2.5/reference-to-video",
"input": {
"prompt": "Use the image for the character and the video for camera motion.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"generate_audio": true,
"reference_image_urls": [
"https://example.com/character.jpg"
],
"reference_video_urls": [
"https://example.com/motion.mp4"
],
"reference_audio_urls": [
"https://example.com/music.mp3"
]
}
}')
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"等待结果
使用 task_id 查询状态。状态为 not_started 或 running 时继续查询;变为 finished 或 failed 时停止,成功后从 data.files[].file_url 读取视频地址。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}建议约每 2 秒查询一次,任务运行时间较长时逐步增加间隔。只在 not_started 或 running 时继续查询;变为 finished 或 failed 后立即停止。也可以在提交请求顶层添加 callback_url。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-08-22T10:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}完整可运行示例
展开后可查看完整脚本,其中包含 HTTP 与业务码检查、task_id 校验、轮询、终态处理和超时控制。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "seedance-2.5/reference-to-video",
"input": {
"prompt": "Use the image for the character and the video for camera motion.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"generate_audio": true,
"reference_image_urls": [
"https://example.com/character.jpg"
],
"reference_video_urls": [
"https://example.com/motion.mp4"
],
"reference_audio_urls": [
"https://example.com/music.mp3"
]
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneinput 参数
下表列出 input 对象支持的字段;请求示例还会展示顶层必填字段 model。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| prompt | string | 是 | — | 去除首尾空格后为 1–20,000 个字符。 |
| duration | integer | 是 | — | 闭区间 4–30 内的整数。 |
| resolution | string | 是 | — | 显式发送 480p 或 720p。 |
| aspect_ratio | string | 否 | — | auto、21:9、16:9、4:3、1:1、3:4 或 9:16。 |
| generate_audio | boolean | 否 | — | 是否请求生成音轨;体验区始终显式发送 true 或 false。 |
| reference_image_urls | string[] | 条件必填 | — | 最多 30 张;参考图片或参考视频至少提供一项。 |
| reference_video_urls | string[] | 条件必填 | — | 最多 10 个,每个视频时长分别向下取整计费。 |
| reference_audio_urls | string[] | 否 | — | 最多 10 个,需与至少一张参考图片或一个参考视频配合使用;三个参考数组合计最多 50 份素材。 |
响应字段
提交成功后会立即返回任务信息;查询状态时可获取进度、输出文件或失败原因。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务返回码;成功响应兼容 0 或 200。 |
| message | string | 接口返回的提示或错误信息。 |
| data.task_id | string | 用于状态查询路径的任务 ID。 |
| data.status | string | not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间。 |
| data.progress | integer | 任务进度,提供时取值为 0–100。 |
| data.files[] | array | 任务成功后返回的全部输出文件,顺序与接口响应一致。 |
| data.files[].file_url | string | 生成视频的公开地址。 |
| data.files[].file_type | string | 文件类型,例如 video。 |
| data.error_message | string | null | failed 状态下的错误详情。 |
任务生命周期
not_started 与 running 是非终态;finished 与 failed 是终态,遇到任一终态都必须停止轮询。
not_started任务已接收,正在等待执行。
running任务正在生成,继续使用同一 task_id 查询。
finished任务成功结束,从 data.files[].file_url 读取全部视频地址。
failed任务执行失败,读取 data.error_message 并停止轮询。
轮询与错误处理
- 认证失败401 表示 Bearer API Key 缺失或无效,修正密钥后再提交。
- 参数或余额错误400 可能表示字段无效、包含不支持的素材字段或积分不足,应先根据消息修正请求。
- 网络与超时网络请求失败不代表任务状态为 failed。请设置合理的超时时间,并重试状态查询。
- 轮询间隔初始间隔约 2 秒,长任务应逐步增加等待时间。
- 终态规则只在 not_started 或 running 时继续,finished 或 failed 都立即停止。
- 回调选项在请求顶层提供 callback_url,可接收最终任务对象;回调投递失败时仍可通过轮询查询结果。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 多模态参考 | 图片可约束人物和画面,视频可提供动作和运镜参考,音频可提供节奏或声音方向。 |
| 素材上限 | 30 / 10 / 10 | 最多 30 张图片、10 个视频、10 个音频,总计不超过 50 个。 |
| 媒体必填 | 图片或视频 | 至少需要一张图片或一个视频作为视觉参考。 |
| 输出 | 视频任务 | 提交后返回异步任务 ID。 |
| 分辨率与时长 | 480p/720p · 4–30 秒 | resolution 与整数 duration 必填。 |
| 计费依据 | 输出 + 参考视频秒数 | 有参考视频时,各视频时长分别向下取整,再与输出时长一起按 17 或 38 积分/秒计费。 |
Seedance 2.5 Reference-to-Video
Seedance 2.5 Reference-to-Video 可结合提示词与图片、视频和可选音频参考,生成带同步音频的新场景。可在提示词中为每份素材指定用途,模型会将参考素材中的人物、构图、视觉风格、动作、运镜、节奏和声音融入生成的视频。
为什么选择此模式?
用图片确定人物和画面风格使用参考图片约束人物、产品、环境、构图或整体视觉风格。
用视频示范动作和运镜当动作、场面调度、运镜或节奏难以用文字说明时,可直接提供参考视频。
用音频提供节奏和声音参考可选音频可以提供环境音、节奏、声音特征或整体声音风格。
明确每份素材的用途在提示词中写清哪份素材用于人物、风格、动作、运镜或声音,避免素材之间互相干扰。
组合多份参考素材复杂场景可同时使用最多 30 张图片、10 个视频和 10 个音频,总数不超过 50 份。
参数说明
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 字符串。说明每份参考素材在新场景中的用途;去除首尾空格后长度为 1–20,000 个字符。 |
| reference_image_urls | 条件必填 | 最多包含 30 个公开图片 URL 的字符串数组,用于指导人物身份、外观、构图、环境或风格。 |
| reference_video_urls | 条件必填 | 最多包含 10 个公开视频 URL 的字符串数组,用于指导动作、镜头移动、调度、速度或镜头节奏。 |
| reference_audio_urls | 可选 | 最多包含 10 个公开音频 URL 的字符串数组,用于指导环境声、节奏、声音特征或整体声音方向。 |
| duration | 必填 | 整数。设置 4–30 秒闭区间内的输出时长;体验区预选 5 秒。 |
| resolution | 必填 | 字符串。设置输出分辨率并必须显式发送;体验区预选 720p。 720p480p |
| aspect_ratio | 可选 | 字符串。控制输出画面比例;体验区预选并显式发送 auto。 auto16:99:161:121:94:33:4 |
| generate_audio | 可选 | 布尔值。请求生成音轨;体验区预选 true,并显式发送当前值。 truefalse |
使用方法
先确定每份素材的用途分别标明素材用于人物身份、产品外观、环境、动作、运镜还是声音。
先准备视觉参考至少提供一张图片或一个视频来确定人物和场景;需要控制节奏或声音时再添加音频。
需要时添加动作参考例如让某个视频只负责舞者动作与镜头节奏,不要把它作为没有边界的整体指令。
在提示词中说明素材关系直接写明每份素材的用途,例如第一张图用于人物,视频用于舞蹈动作,音频用于节拍。
生成前检查素材是否冲突设置输出参数前,先移除在人物身份、运镜、光线或动作顺序上互相矛盾的素材。
设置输出参数参考关系明确后,再设置时长、分辨率、画面比例和生成音频。
生成并检查结果运行任务后检查各份参考素材是否按预期生效;需要迭代时,可精简素材或重新说明它们的用途。
计费
没有参考视频时按输出秒计费;只要有参考视频,输出秒数与各视频分别向下取整后的时长全部使用 with-video 费率。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 480p,无参考视频 | 28 积分/输出秒($0.140/输出秒) | 5 秒仅图片任务为 140 积分($0.700)。 |
| 720p,无参考视频 | 63 积分/输出秒($0.315/输出秒) | 5 秒仅图片任务为 315 积分($1.58)。 |
| 480p,含参考视频 | 17 积分/计费秒($0.085/计费秒) | 5 秒输出加 2.9 秒与 3.8 秒视频,按 5 + 2 + 3 = 10 秒,费用为 170 积分($0.850)。 |
| 720p,含参考视频 | 38 积分/计费秒($0.190/计费秒) | 同一 10 个计费秒为 380 积分($1.90);未知视频时长时页面只显示可证明的最低价。 |
适用场景
系列角色内容结合角色设定图、服装图片和场景提示词,为同一人物生成多段表演视频。
舞蹈与运镜预演结合角色图片和动作视频,生成用于评估表演、场面调度、运镜和节奏的预演片段。
产品宣传片变体组合产品图、环境图和风格参考,再加入新的动作设计,生成多版宣传视频。
音乐表演概念片结合表演者图片、舞蹈视频和音频参考,生成音乐视频或舞台表演概念片段。
实用技巧
- 在提示词中直接注明每份素材的用途,例如人物、服装、产品、环境、动作、运镜、声音或节奏。
- 不要只写“使用全部参考素材”,应说明具体关系,例如沿用第一张图的人物、参考第一个视频的动作,并使用第一段音频的节拍。
- 继续增加描述前,先移除在人物身份、光线、镜头方向或时序上互相冲突的素材。
注意事项
- 至少提供一张参考图片或一个参考视频;参考音频可以与这些视觉素材配合使用。
- 三个参考数组分别遵守各自上限,素材总数不得超过 50 份。
- 上传完成后,每个素材地址都必须是公开且可直接下载的 HTTP(S) URL。
Seedance 2.5 参考生视频 API — 常见问题
Seedance 2.5 Reference-to-Video API 是什么?
Seedance 2.5 由 ByteDance Seed 开发。Reference-to-Video API 根据提示词以及至少一张参考图片或一个参考视频,异步生成新视频。你还可以继续添加图片、视频或音频参考,三类素材合计最多 50 份,并选择是否同步生成音频。
如何调用 Seedance 2.5 Reference-to-Video API?
使用 Bearer API Key 向 /api/generate/submit 发起 POST 请求,将 model 设为 seedance-2.5/reference-to-video,并把生成参数放入 input。提交成功后会立即返回 task_id;API 标签页和完整文档中提供了可运行示例。
查看完整 API 文档Seedance 2.5 Reference-to-Video API 如何计费?
无参考视频时,480p 为 28 积分/输出秒,720p 为 63 积分/输出秒。存在参考视频时,输出秒数加各视频分别向下取整后的时长使用 17 或 38 积分/计费秒。例如 5 秒 480p 输出加 2.9 秒和 3.8 秒参考视频,共计 10 个计费秒,费用为 170 积分($0.850)。
Seedance 2.5 Reference-to-Video API 接受哪些输入?
input 最多接受 30 张图片、10 个视频和 10 个音频,三类参考素材合计不超过 50 个。至少使用一张图片或一个视频,音频可以配合这些视觉参考使用。
如何获取生成的视频?
使用 task_id 轮询 GET /api/generate/status/{task_id}。状态为 finished 时从 data.files[].file_url 读取视频地址;状态为 failed 时停止轮询并读取错误信息。也可以通过 callback_url 接收最终结果。
应该选择哪个 Seedance 2.5 端点?
不同素材需要明确承担外观、动作、镜头或声音角色时选择 Reference-to-Video;只从文字开始时选择 Text-to-Video;已有必填首帧和可选尾帧时选择 Image-to-Video。

