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.
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。
2/10 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。
1/5 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。
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
提交一次生成任务
使用本工作流最小合法请求体提交。成功提交会立即返回 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 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 提供实验室环境底噪”。清晰的角色与素材绑定可避免模型产生多主体特征混淆。















