Use the two reference images only for this long-legged porcelain teapot: spout, lid, floral glaze, and stork-like legs. New 4-second 1:1 scene: the teapot stomps across a wooden dining table, each footfall making cups rattle. Locked three-quarter camera. Native audio: ceramic foot stomps, cup chatter, table creak. Image references only. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.
Wan 3.0 Prime Reference-to-Video API
alibaba/wan-3.0-prime/reference-to-videoWan 3.0 Prime(Reference-to-Video)将文本提示词与图片、视频、音频、文档或链接参考转化为最长 30 秒的连续视频,支持 Omni-Reference 多模态参考、原生音画同步,以及最高 1080p 输出。它按提示词中的角色分配,把身份、道具、动作线索与空间关系带入新场景。
输入
请至少添加一种参考素材:图片、视频、音频、文档 URL 或网页 URL。
输出
等待运行生成的视频会显示在这里
设置必填输入、分辨率和时长,然后运行任务。
继续使用
示例
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
提交一次生成任务
使用本工作流最小合法请求体提交。成功提交会立即返回 task_id,无需等待视频完成。 可仅使用音频作为参考,仍须提供提示词。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-3.0-prime/reference-to-video",
"input": {
"prompt": "Use image 1 for the fox's face, fur, and oversized white lab coat. Use video 1 only for the walking gait and tail sway. Use audio 1 for the laboratory room-tone: HVAC hum and distant glass. New 5-second 16:9 scene: the same fox walks along a lab bench, pauses, and sniffs a bubbling beaker. Medium tracking shot, eye level. Native audio: the supplied lab room-tone plus paw steps. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"audio": true,
"enable_safety_checker": true,
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-01.webp",
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-02.webp"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-motion.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-audio.mp3"
]
}
}
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": "alibaba/wan-3.0-prime/reference-to-video",
"input": {
"prompt": "Use image 1 for the fox's face, fur, and oversized white lab coat. Use video 1 only for the walking gait and tail sway. Use audio 1 for the laboratory room-tone: HVAC hum and distant glass. New 5-second 16:9 scene: the same fox walks along a lab bench, pauses, and sniffs a bubbling beaker. Medium tracking shot, eye level. Native audio: the supplied lab room-tone plus paw steps. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"audio": true,
"enable_safety_checker": true,
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-01.webp",
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-02.webp"
],
"reference_video_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-motion.mp4"
],
"reference_audio_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-3.0-prime/reference-to-video/v1/01/input-audio.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
done输入参数
以下字段位于 input 内。请求示例还包含必填的顶层 model 字段。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| prompt | string | 是 | — | 去除首尾空白后 1–20,000 字符。 |
| reference_image_urls | string[] | 条件 | — | 使用图片参考时提供 1–10 个公开图片 URL。 |
| reference_video_urls | string[] | 条件 | — | 使用视频参考时提供 1–5 个公开视频 URL。 |
| reference_audio_urls | string[] | 条件 | — | 使用音频参考时提供 1–5 个公开音频 URL。 可作为唯一参考类型。 |
| reference_file_urls | string[] | 条件 | — | 恰好 1 个公开文件 URL;与 reference_link_urls 互斥。 |
| reference_link_urls | string[] | 条件 | — | 恰好 1 个公开链接 URL;与 reference_file_urls 互斥。 |
| duration | integer | 否 | 5 | 整数,范围 2–30(含端点)。 |
| resolution | string | 否 | 720p | 480p、720p 或 1080p。 |
| aspect_ratio | string | 否 | adaptive | adaptive、16:9、4:3、1:1、3:4 或 9:16。 |
| audio | boolean | 否 | true | 是否请求音轨;不影响积分费率。 |
| seed | integer | 否 | — | 可选整数,范围 0–2147483647。 |
| enable_safety_checker | boolean | 否 | true | 是否启用安全检查。 |
响应字段
提交后立即返回任务标识。状态响应会补充进度、全部输出文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务结果码;成功响应为 0 或 200。 |
| message | string | 可读消息或错误说明(如有)。 |
| data.task_id | string | 用于状态查询路径的任务 ID。 |
| data.status | string | not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间(date-time)。 |
| data.progress | integer | 提供方返回的进度,范围 0–100。 |
| data.files[] | array | 成功任务的全部输出文件,按响应顺序排列。 |
| data.files[].file_url | string | 生成视频的公开 URL。 |
| data.files[].file_type | string | 文件类型,例如 video。 |
| data.error_message | string | null | status 为 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 接收最终扁平任务对象;若投递失败仍可继续轮询。
接口规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 提示词 + 参考 | 需要 prompt,并至少提供一种图片、视频、音频、文件或链接参考。 |
| 输出 | 视频任务 | 接口返回异步任务 ID。 |
| 分辨率 | 480p / 720p / 1080p | 省略时 resolution 默认为 720p。 |
| 时长 | 2–30 秒 | 区间内每个整数均有效;默认 5。 |
| 画面比例 | Adaptive + 5 种固定比例 | adaptive、16:9、4:3、1:1、3:4 或 9:16。 |
| 计费基础 | 输出秒数 | 480p 为 13.6 积分/秒;720p 为 28 积分/秒;1080p 为 56 积分/秒。 |
Wan 3.0 Prime Reference-to-Video
Wan 3.0 Prime Reference-to-Video 根据必填提示词与混合参考生成带可选同步声音的连续片段。当每份素材被赋予清晰用途时,它把主体外观、运动节奏、运镜语言与声音线索带入新场景。
为什么选择此模式?
Reference-to-Video结合提示词与图片、视频、音频、文档或链接参考,生成全新的连续场景。
主体延续把既有人物、产品、声音或空间带进提示词驱动的新片段,而不只靠文字重写身份。
多模态参考分工最多使用 10 张图、5 段视频、5 段音频,或一份文件 / 一个链接,并为每份素材指定创作职责。
原生音画同步保持音频开启,随画面一同生成对白、环境音、音效或音乐。
分层提示词控制把每份参考映射到身份、动作、运镜或声音,再写清新场景时间线。
交付规格输出 480p、720p 或 1080p,时长 2–30 秒,并支持 adaptive 与固定画幅。
参数
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 字符串。定义每个参考如何贡献到新场景;去除首尾空白后长度为 1–20,000 字符。 |
| reference_image_urls | 条件必填 | 1–10 个公开图片 URL 的字符串数组,用于引导身份、外观、构图、环境或风格。 |
| reference_video_urls | 条件必填 | 1–5 个公开视频 URL 的字符串数组,用于引导动作、运镜、调度、节奏或镜头韵律。 |
| reference_audio_urls | 条件必填 | 1–5 个公开音频 URL 的字符串数组,用于引导环境音、节奏、声线或声音方向。 |
| reference_file_urls | 条件必填 | 恰好 1 个公开文件 URL,用于提交打包参考文件;与 reference_link_urls 互斥。 |
| reference_link_urls | 条件必填 | 恰好 1 个公开链接 URL,用于提交链接参考包;与 reference_file_urls 互斥。 |
| duration | 可选 | 整数。输出时长为 2–30 秒(含端点);默认 5。 |
| resolution | 可选 | 字符串。输出分辨率;默认 720p。 480p720p1080p |
| aspect_ratio | 可选 | 字符串。控制画面比例;默认 adaptive。 adaptive16:94:31:13:49:16 |
| audio | 可选 | 布尔值。是否生成音轨;默认 true。开启或关闭音频不会改变费率。 truefalse |
| seed | 可选 | 整数。可选复现种子,范围 0–2147483647。 |
| enable_safety_checker | 可选 | 布尔值。是否启用安全检查;默认 true。 truefalse |
使用方法
先定每份素材的用途标明参考负责人物身份、产品外观、环境、动作、运镜、声音或节奏中的哪一项。
添加参考锚点至少提供 reference_image_urls、reference_video_urls、reference_audio_urls、reference_file_urls 或 reference_link_urls 之一,并遵守数量上限。
在提示词中写对应关系写清楚:第一张图是讲者外观,第一段视频管走位,第一段音频只管环境底噪。
设置时长选择 2–30 的整秒时长;首次试片默认可用 5 秒。
选择分辨率用 480p 检查参考角色是否成立,用 720p 或 1080p 做评审与交付。
选择画幅比例在 adaptive、16:9、4:3、1:1、3:4、9:16 中选择匹配渠道的画幅。
配置音频需要同步声音时保持音频开启;制作静音片段时关闭该选项。
生成视频点击「运行」,任务完成后在输出区检查哪些参考角色进入了成片。
价格
费用仅取决于输出时长与分辨率;音频开关不改变费率。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 480p | 13.6 积分/输出秒($0.068/秒) | 2 秒计 27.2 积分($0.136),5 秒计 68 积分($0.340),30 秒计 408 积分($2.04)。 |
| 720p | 28 积分/输出秒($0.14/秒) | 2 秒计 56 积分($0.280),5 秒计 140 积分($0.70),30 秒计 840 积分($4.20)。 |
| 1080p | 56 积分/输出秒($0.28/秒) | 2 秒计 112 积分($0.560),5 秒计 280 积分($1.40),30 秒计 1,680 积分($8.40)。 |
推荐使用场景
品牌套件成片把产品静帧、场地照片、短动作参考与锁定 Logo 放进一次请求,用新提示词做成品牌片段。
角色或产品跨镜延续把角色设定、服装或产品主视觉带进新的表演或演示场景。
讲义或报告转解说用一份参考文件或公开网页素材包,把结构化内容做成解说片段。
动作与声音对齐的活动片用人物图 + 动作视频 + 人声或节奏轨,让新片子跟随这些参考。
多素材分镜组装把已批准的视觉、动作与音频参考组装成一条预演镜头,供创意评审。
专业技巧
- 在提示词里给每份素材标注用途:人物、服装、产品、空间、动作、运镜、声音或节奏。
- 不要写「使用全部参考」;改成关系句:人物跟第一张图,走位跟第一段视频,第一段音频只提供节奏。
- 守住数量上限:最多 10 张图、5 段视频、5 段音频;使用文档或网页时仅选一份文件或一个链接。
- 按时长与画幅意图 → 主体与参考资产 → 场景与光影 → 运镜与机位 → 对白与声音 → 时间线组织提示词。
- 先用 480p / 5 秒验证参考角色,身份与时序成立后再渲染 1080p 与更长时长。
注意事项
- 至少提供一个参考数组;reference_file_urls 与 reference_link_urls 互斥。
- 生成是异步的;保存 task_id,并在任务到达 finished 或 failed 时停止查询。
Wan 3.0 Prime Reference-to-Video API — 常见问题
Wan 3.0 Prime Reference-to-Video API 是什么?
Wan 3.0 Prime Reference-to-Video 是阿里通义实验室研发的旗舰级多模态参考生成视频模型。它支持协同输入提示词与多张图片、视频片段、音频、结构化文档或网页链接,生成最长 30 秒、最高 1080p 的高保真音画同步视频。基于前沿的全模态交叉注意力架构,它能够在复杂的多镜头叙事中严谨保持主体身份与品牌资产一致性,实现影视级的创意延展。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Wan 3.0 Prime 参考生视频能组合哪些类型的参考素材?
支持五大类参考素材:最多 10 张参考图片、最多 5 个参考视频、最多 5 段参考音频,以及最多 1 个结构化文档或网页链接。你可以根据创作需要灵活组合,例如用图片定角色、用视频定走位、用音频定节奏。
Wan 3.0 Prime 参考生视频能跨镜头稳定保留产品外观吗?
能。对于电商展示或商业广告,模型能够学习多张参考图中商品的外观轮廓、特殊材质与品牌标识,在新设计的镜头轨迹与多角度光影中稳定展现产品质感,杜绝形变走样。
Wan 3.0 Prime 参考生视频如何处理参考视频的动态与运镜?
传入 reference_video_urls 时,模型会提取源视频中的主体运动姿态、步伐节奏或摄影机轨迹,并将其迁移到新角色与新场景中,实现动作重定向与运镜复用。
Wan 3.0 Prime 参考生视频支持用企业文档直接生成宣传片吗?
支持。可在 reference_file_urls 中上传单份 PPT、PDF、DOCX 等文档,模型能深入理解文档的结构图表与核心叙事逻辑,自动提炼视觉要点并生成具宣讲声场的动态视频。
文档与网页链接在 Wan 3.0 Prime 参考生视频中能同时传吗?
不能。结构化文档与网页链接为互斥参数,单次请求仅能选择其一传入。推荐直接使用最能完整表达核心信息的单一格式源(例如完整的演示文档或独立的公开落地页)。
如何在提示词中清晰界定 Wan 3.0 Prime 多个参考角色的关系?
建议使用明确的素材编号映射指令,例如“参考图 1 和 2 对应主角研究员的外观与白大褂,参考视频 1 对应助手的步伐走位,参考音频 1 提供实验室环境底噪”。清晰的角色与素材绑定可避免模型产生多主体特征混淆。
