Seedance 2.5 Flash Reference to Video API
seedance-2.5-flash/reference-to-videoSeedance 2.5 Flash Reference to Video 用最多 10 图、5 视频、5 音频参考生成 4–30 秒同步音频视频。为每个参考指定外观、动作或声音,把人物延续到新场景。
输入
拖拽文件、粘贴剪贴板素材,或输入 URL。 JPEG, PNG, or WebP, up to 30 MB
1/10 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 MP4 or MOV, 2–30 seconds, up to 50 MB
1/5 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 MP3 or WAV, 2–30 seconds, up to 15 MB
1/5 个素材
输出
已就绪继续使用
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,无需等待视频生成完成。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "seedance-2.5-flash/reference-to-video",
"input": {
"prompt": "Use @Image1 for the character's look and @Video1 for the walking motion. The character crosses a sunlit plaza.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"reference_image_urls": [
"https://example.com/character.png"
],
"reference_video_urls": [
"https://example.com/walk-motion.mp4"
],
"generate_audio": true
}
}
JSON
)
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")
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-flash/reference-to-video",
"input": {
"prompt": "Use @Image1 for the character's look and @Video1 for the walking motion. The character crosses a sunlit plaza.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"reference_image_urls": [
"https://example.com/character.png"
],
"reference_video_urls": [
"https://example.com/walk-motion.mp4"
],
"generate_audio": true
}
}
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 | 是 | — | 描述画面的文本提示词。 |
| duration | integer | 是 | — | 4–30 闭区间内的整数。 |
| reference_image_urls | string[] | 否 | — | 最多 10 个;与参考视频至少提供一种。 |
| reference_video_urls | string[] | 否 | — | 最多 5 个 MP4 或 MOV,每段 2–30 秒,总时长 30 秒以内,每个视频的整秒数计入计费。 |
| reference_audio_urls | string[] | 否 | — | 最多 5 个 MP3 或 WAV,每段 2–30 秒,总时长 30 秒以内,与参考图或参考视频搭配使用。 |
| resolution | string | 否 | 720p | 480p 或 720p。 |
| aspect_ratio | string | 否 | — | auto、21:9、16:9、4:3、1:1、3:4 或 9:16。 |
| generate_audio | boolean | 否 | — | 是否生成同步音频;开启或关闭单价相同。 |
响应字段
提交成功后会立即返回任务信息;查询状态时可获取进度、输出文件或失败原因。
| 字段 | 类型 | 说明 |
|---|---|---|
| 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,可接收最终任务对象;回调投递失败时仍可通过轮询查询结果。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 参考图 / 视频 / 音频 | 最多 10 张图、5 段视频、5 段音频;至少一张图或一段视频。 |
| 输出 | 视频任务 | 接口返回异步任务 ID,成片包含可选同步音频。 |
| 分辨率 | 480p / 720p | 默认 720p。 |
| 时长 | 4–30 秒 | 闭区间内任意整数秒。 |
| 画幅 | 自动 + 6 种固定 | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16. |
| 计费依据 | 输出秒 + 参考视频秒 | 标准单价 18.5 / 41 积分/秒;含参考视频 11.5 / 25.5 积分/计费秒(480p / 720p)。 |
相关模型
Seedance 2.5 Flash Reference to Video API 常见问题
Seedance 2.5 Flash Reference to Video API 是什么?
Seedance 2.5 Flash Reference to Video 是字节跳动 Seed 团队用于根据参考图片、视频和音频生成视频的模型。它组合最多 10 张图、5 段视频和 5 段音频,生成 480p 或 720p 的 4–30 秒视频,支持可选同步音频。它基于 Seedance 2.5 的多模态参考工作流,把你指定的人物外观、动作、运镜和声音延续到新场景中。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Seedance 2.5 Flash Reference to Video 最多支持多少个参考素材?
每次请求最多 10 张参考图、5 段参考视频和 5 段参考音频。至少包含一张图或一段视频,参考音频需与它们一起使用。需要更多参考时,Seedance 2.5 Reference to Video 最多支持 50 个素材。
Seedance 2.5 Flash Reference to Video 的参考视频怎么计费?
请求包含参考视频时,计费秒数为输出时长加上每个参考视频的整秒数,480p 每秒 11.5 积分,720p 每秒 25.5 积分。720p 输出 10 秒并搭配 10 秒参考视频,按 20 秒计费为 510 积分($2.55)。以参考图或参考音频引导的请求按标准单价计费,每输出秒 18.5 和 41 积分。
Seedance 2.5 Flash Reference to Video 的参考视频最长多久?
每段参考视频或音频时长为 2–30 秒;参考视频总时长最多 30 秒,参考音频总时长同样最多 30 秒。把每段素材裁剪到需要的动作或声音片段,较短的参考视频也会减少计费秒数。
Seedance 2.5 Flash Reference to Video 能用音频做参考吗?
能。最多添加 5 段参考音频,并搭配至少一张参考图或一段参考视频。在提示词中写明音频要引导的内容,例如音乐、环境声或动作节拍。
Seedance 2.5 Flash Reference to Video 如何给参考素材分配作用?
在提示词中按上传顺序用 @Image1、@Video1、@Audio1 指代素材,每种类型单独编号。写明每个素材提供什么,例如沿用参考视频 1 的走路动作,背景由提示词另行描述。
什么时候该选 Seedance 2.5 Reference to Video 而不是 Flash 版本?
镜头需要 1080p 输出,或参考素材超过 10 张图、5 段视频、5 段音频时,选择 Seedance 2.5 Reference to Video,它最多支持 30、10、10 个。Flash 使用相同字段,以更低单价完成 480p 与 720p 创作。
Seedance 2.5 Flash Reference to Video 支持哪些画幅?
可选择 auto,或 21:9、16:9、4:3、1:1、3:4、9:16 六种固定画幅。输出格式与参考素材不同时,例如用横屏素材制作 9:16 社交视频,可指定固定画幅。















