Use Reference Image 1 only for the fictional courier's face, short dark curly hair, cobalt-blue waterproof jacket, charcoal trousers, gray gloves, body proportions, and blue electric cargo tricycle. Use Reference Video 1 only for the start-and-pull-away action, natural weight shift, low side-tracking camera path, wet-road tire spray, and action timing; do not copy its amber-coated rider, red scooter, noodle stall, or night-market layout. Use Reference Audio 1 only for the engine-start cue, rain intensity, tire hiss, and timing; do not add music. Create one continuous four-second shot under the covered flower-market arcade shown by the reference identity: the courier mounts the blue cargo tricycle, starts it, and pulls forward past the flower buckets while preserving the referenced face, clothing, vehicle, roof, and wet-stone setting. No cuts, no extra people, no dialogue, no readable text, no logos, no products, no advertising, no watermark.
Seedance 2.0 Mini Reference-to-Video API
bytedance/seedance-2.0-mini/reference-to-videoSeedance 2.0 Mini Reference-to-Video API 根据提示词以及图片、视频和可选音频参考生成 4–15 秒的 480p 或 720p 视频。每次请求最多包含 9 张图片、3 个视频和 3 个音频文件,三类文件合计不超过 12 个,并且至少包含一张图片或一个视频。
输入
生成音频
请求模型随视频生成音轨。
高级参数
返回最后一帧
保留视频主结果,并把最后一帧作为额外文件返回。
联网搜索
发送可选的 web_search 布尔字段。
输出
等待运行生成文件会显示在这里
设置输入、选择时长,然后运行异步视频任务。
继续使用
示例
REST API
快速开始
认证,提交一张公开参考图片,然后取得异步任务中的全部文件。
连接 Vidgo API
在服务端保存 VIDGO_API_KEY,并通过 Bearer Header 发送。
- 接口
- POST
https://api.vidgo.ai/api/generate/submit - 认证
- Authorization: Bearer VIDGO_API_KEY
提交一个生成任务
最小请求包含提示词、时长以及至少一个参考图片或视频。
curl --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.0-mini/reference-to-video",
"callback_url": "https://webhook.site/b3fc9007-e1ec-4df1-97da-fd65c209e5d6",
"input": {
"prompt": "Use Reference Image 1 only for the fictional courier's face, short dark curly hair, cobalt-blue waterproof jacket, charcoal trousers, gray gloves, body proportions, and blue electric cargo tricycle. Use Reference Video 1 only for the start-and-pull-away action, natural weight shift, low side-tracking camera path, wet-road tire spray, and action timing; do not copy its amber-coated rider, red scooter, noodle stall, or night-market layout. Use Reference Audio 1 only for the engine-start cue, rain intensity, tire hiss, and timing; do not add music. Create one continuous four-second shot under the covered flower-market arcade shown by the reference identity: the courier mounts the blue cargo tricycle, starts it, and pulls forward past the flower buckets while preserving the referenced face, clothing, vehicle, roof, and wet-stone setting. No cuts, no extra people, no dialogue, no readable text, no logos, no products, no advertising, no watermark.",
"duration": 4,
"resolution": "720p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-image.png"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-video.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-audio.mp3"
],
"generate_audio": true,
"seed": 24082403
}
}'等待结果
只轮询非终态,或使用 callback_url;保留全部成功文件。
查询状态
GET https://api.vidgo.ai/api/generate/status/KV7E99PXH1WTZJDD初始每 2–5 秒查询,长任务逐步退避;finished 或 failed 停止。网络超时与任务失败分别处理,callback_url 接收扁平终态对象。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "KV7E99PXH1WTZJDD",
"status": "running",
"created_time": "2026-08-24T09:01:21"
}
}{
"code": 200,
"data": {
"task_id": "KV7E99PXH1WTZJDD",
"status": "finished",
"created_time": "2026-08-24T09:01:21",
"progress": 100,
"error_message": null,
"files": [
{
"file_type": "video",
"file_url": "https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/output.mp4"
}
]
}
}完整可运行示例
展开脚本包含提交、轮询、失败、超时和文件提取。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "seedance-2.0-mini/reference-to-video",
"callback_url": "https://webhook.site/b3fc9007-e1ec-4df1-97da-fd65c209e5d6",
"input": {
"prompt": "Use Reference Image 1 only for the fictional courier's face, short dark curly hair, cobalt-blue waterproof jacket, charcoal trousers, gray gloves, body proportions, and blue electric cargo tricycle. Use Reference Video 1 only for the start-and-pull-away action, natural weight shift, low side-tracking camera path, wet-road tire spray, and action timing; do not copy its amber-coated rider, red scooter, noodle stall, or night-market layout. Use Reference Audio 1 only for the engine-start cue, rain intensity, tire hiss, and timing; do not add music. Create one continuous four-second shot under the covered flower-market arcade shown by the reference identity: the courier mounts the blue cargo tricycle, starts it, and pulls forward past the flower buckets while preserving the referenced face, clothing, vehicle, roof, and wet-stone setting. No cuts, no extra people, no dialogue, no readable text, no logos, no products, no advertising, no watermark.",
"duration": 4,
"resolution": "720p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-image.png"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-video.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/bytedance/seedance-2.0-mini/reference-to-video/v1/input-reference-audio.mp3"
],
"generate_audio": true,
"seed": 24082403
}
}
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')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/KV7E99PXH1WTZJDD" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
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 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数
model 与 callback_url 位于顶层;input 接受公共字段和三类参考数组,内部计费字段绝不是公开输入。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | 必须为 seedance-2.0-mini/reference-to-video。 |
| callback_url | string (URL) | 否 | — | 公开终态回调地址。 |
| input | object | 是 | — | 模型输入对象。 |
| input.prompt | string | 是 | — | trim 后 1–20,000。 |
| input.reference_image_urls | string[] | 条件 | — | 最多 9,图片或视频至少一类。 |
| input.reference_video_urls | string[] | 条件 | — | 最多 3,时长影响计费。 |
| input.reference_audio_urls | string[] | 否 | — | 最多 3,不能单独使用;三类合计最多 12。 |
| input.duration | integer | 是 | — | 4–15 的整数,包括 4 和 15。 |
| input.resolution | string | 否 | 720p | 480p 或 720p。 |
| input.aspect_ratio | string | 否 | — | auto 与六种固定比例。 |
| input.generate_audio | boolean | 否 | — | 生成音频。 |
| input.return_last_frame | boolean | 否 | — | 额外最后一帧。 |
| input.web_search | boolean | 否 | — | 可选的 boolean 字段。 |
| input.seed | integer | 否 | — | 无公开范围。 |
响应字段
提交返回任务身份;状态返回进度、全部文件或终态错误。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务码,成功为 0 或 200。 |
| message | string | 响应消息。 |
| data.task_id | string | 状态 ID。 |
| data.status | string | 四种公开状态。 |
| data.created_time | string | 创建时间。 |
| data.progress | integer | 进度。 |
| data.files[] | array | 全部成功文件。 |
| data.files[].file_url | string | 结果 URL。 |
| data.files[].file_type | string | 媒体类型。 |
| data.files[].watermark_url | string | null | 水印地址。 |
| data.error_message | string | null | 失败信息。 |
任务生命周期
只轮询非终态。
not_started已接收并排队。
running生成中。
finished成功终态,读取全部文件。
failed失败终态,停止并读取错误。
轮询与错误
- 认证401 表示 Bearer Key 缺失或无效。
- 校验400 表示类型、单类上限、总数或条件无效。
- 轮询间隔从 2–5 秒开始,长任务、429 或 5xx 退避。
- 终态finished 或 failed 立即停止,并设置超时。
- 回调callback_url 接收扁平终态任务对象。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 图片、视频和音频参考 | 图片 9、视频 3、音频 3、总计 12。 |
| 输出 | 视频 + 可选最后一帧 | 异步混合文件结果。 |
| 分辨率 | 480p / 720p | 默认 720p。 |
| 时长 | 4–15 秒 | 整数范围。 |
| 视觉必填 | 图片或视频 | 音频不能单独提交。 |
| 计费 | 6–24 积分/秒 | 由分辨率和是否存在参考视频决定。 |
Seedance 2.0 Mini 参考生视频 API 概览
Seedance 2.0 Mini Reference-to-Video API 使用 reference_image_urls、reference_video_urls 和 reference_audio_urls 接收参考文件。prompt 需要逐项说明图片、视频或音频用于提供哪些外观、动作、镜头或声音信息。
为什么使用 Seedance 2.0 Mini Reference-to-Video API?
提交最多 9 张参考图片。图片可以提供主体、产品、环境、服装或视觉风格信息。
提交最多 3 个参考视频。视频可以提供主体动作、动作时序和镜头移动信息。
提交最多 3 个参考音频。音频可以提供节奏、环境声、音效或对白信息,但不能单独提交。
在一次请求中组合三类文件。图片、视频和音频可以同时提交,三类文件合计不得超过 12 个。
参数
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | trim 后 1–20,000 个字符,并说明每个参考素材的职责。 |
| reference_image_urls | 条件必填 | 最多 9 个公开图片 URL;图片或视频至少有一类。 |
| reference_video_urls | 条件必填 | 最多 3 个公开视频 URL;每段时长分别向下取整后参与计费。 |
| reference_audio_urls | 可选 | 最多 3 个公开音频 URL;不能单独提交。 |
| duration | 必填 | 4–15 秒整数;Playground 初始为 5 秒。 |
| resolution | 可选 | API 与 Playground 默认 720p。 默认值 720p480p |
| aspect_ratio | 可选 | Auto 或六种固定比例;Playground 初始为 Auto。 auto16:99:161:121:94:33:4 |
| generate_audio | 可选 | boolean;Playground 初始发送 true。 |
| return_last_frame | 可选 | 请求额外最后一帧。 |
| web_search | 可选 | boolean 字段。 |
| seed | 可选 | 无公开范围的整数。 |
使用方法
给每类素材分配职责说明图片提供哪些外观信息、视频提供哪些动作或镜头信息、音频提供哪些声音信息。
添加图片或视频参考至少提供一张图片或一个视频,音频单独提交无效。
核对总数图片 9、视频 3、音频 3,且三类合计最多 12 个。
在提示词中指明引用关系明确哪个素材负责身份、动作、镜头或声音。
提交并跟踪运行请求,然后轮询 task_id 或接收终态回调。
价格
没有参考视频时只按输出秒数使用标准费率。存在任一参考视频时,输出秒数与每段参考视频分别 floor 后的秒数之和,全部使用 with-video 费率。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 480p,无参考视频 | 10 积分 / 输出秒 | $0.050/秒;5 秒输出为 50 积分。 |
| 720p,无参考视频 | 24 积分 / 输出秒 | $0.120/秒;5 秒输出为 120 积分。 |
| 480p,含参考视频 | 6 积分 / 计费秒 | $0.030 ×(输出秒数 + sum(floor(每段参考视频时长)))。 |
| 720p,含参考视频 | 12.5 积分 / 计费秒 | $0.0625 ×(输出秒数 + sum(floor(每段参考视频时长)))。 |
适用场景
角色外观与动作参考提交角色图片提供外观信息,并提交动作视频提供运动信息。
产品外观与动作参考提交产品图片提供设计信息,并提交视频提供移动或操作方式。
参考视频中的镜头移动在 prompt 中要求生成视频参考素材的横移、推进、环绕或跟随方式。
音频节奏与声音参考将图片或视频与提供节奏、环境声、音效或对白信息的音频一起提交。
提示词技巧
- 明确每张图片提供主体外观、服装、环境还是风格信息,不要只写“使用参考图”。
- 分别说明参考视频提供的主体动作与镜头移动。
- 音频可以提供节奏、环境声或对白信息,但必须同时提交图片或视频。
- 只提交与当前生成目标有关的文件,删除内容相互冲突的参考素材。
- 需要显示精确价格前,先确认每段参考视频的时长已经读取。
注意事项
- 上限为图片 9、视频 3、音频 3,三类合计 12,而不是 15。
- 音频不能单独提交,至少需要一张参考图片或一个参考视频。
- 参考视频按文件分别向下取整,再把全部计费秒数乘同一含视频费率。
- 参考视频的计费秒数由服务端计算,不属于公开请求输入。
- 存在未知视频时长时只显示最低价,不伪造精确金额。
Seedance 2.0 Mini Reference-to-Video API — 常见问题
Seedance 2.0 Mini Reference-to-Video API 是什么?
Seedance 2.0 Mini Reference-to-Video API 根据提示词以及图片、视频和可选音频参考生成视频。请求成功后返回 task_id,任务完成后生成文件位于 data.files。
如何调用 Seedance 2.0 Mini Reference-to-Video API?
使用 Bearer Key 向 /api/generate/submit 发送 POST,将模型 ID 设置为 seedance-2.0-mini/reference-to-video,并提供 prompt、duration 以及至少一个公开图片或视频 URL。取得 task_id 后查询任务状态,或提供 callback_url。
Seedance 2.0 Mini Reference-to-Video API 如何计费?
没有参考视频时,480p 每个输出秒使用 10 积分,720p 每个输出秒使用 24 积分。包含参考视频时,480p 每个计费秒使用 6 积分,720p 每个计费秒使用 12.5 积分;计费秒为输出时长加上每个参考视频分别向下取整后的时长。
Seedance 2.0 Mini Reference-to-Video API 支持哪些输入?
每次请求最多包含 9 张图片、3 个视频和 3 个音频文件,三类合计最多 12 个。至少需要一张图片或一个视频,音频不能单独提交。
如何获取 Seedance 2.0 Mini Reference-to-Video API 的生成结果?
仅在状态为 not_started 或 running 时查询任务。状态变为 finished 或 failed 后停止查询,并读取 data.files 中的全部成功文件或 data.error_message。
三种 Seedance 2.0 Mini API 应该如何选择?
需要图片、视频或音频参考时使用 Seedance 2.0 Mini Reference-to-Video API;需要首帧和可选尾帧时使用 Seedance 2.0 Mini Image-to-Video API;没有源素材时使用 Seedance 2.0 Mini Text-to-Video API。


