Use the exact yellow robot from the reference video as the sole character. Place it on a stone path inside a daylight fern greenhouse. Preserve the mustard rectangular torso, single turquoise eye, short arms with two-finger grippers and broad grey feet. In one full-body three-quarter shot, it bends slightly forward to inspect a large fern frond without touching it, then tilts its rectangular upper body a little to one side. Gentle servo sounds and greenhouse ambience. A completely new leafy glasshouse background. No speech, music, text or cuts.
Wan 2.6 Reference to Video API
alibaba/wan-2.6/reference-to-videoWan 2.6 Reference to Video 支持输入 1–10 个参考视频片段与提示词,合成 5–10 秒 1080p 电影级动态成片,提供多源参考融合、多镜头过渡与自适应机位编排。它在保留参考素材中动作节奏、运动轨迹与光影质感的同时,精准响应提示词中的全新剧情走向与主体形态约束。
必填 1–10 个视频。支持 MP4、MOV、MKV,每个最大 10MiB。
示例
REST API 规格
快速开始
提交端点请求并查询任务状态。请将示例素材 URL 替换为可访问的真实文件。
第一步:配置 API 鉴权
在控制台申请 API Key,并在每个 HTTP 请求头中携带 Authorization: Bearer <API_KEY> 进行身份验证。
- 任务提交端点
- POST
https://api.vidgo.ai/api/generate/submit - 鉴权请求头
- Authorization: Bearer VIDGO_API_KEY
第 2 步:提交生成任务
POST /api/generate/submit。model 和可选 callback_url 位于根级,生成参数位于 input 内。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-2.6/reference-to-video",
"input": {
"prompt": "Use the exact yellow robot from the reference video as the sole character. Place it on a stone path inside a daylight fern greenhouse. Preserve the mustard rectangular torso, single turquoise eye, short arms with two-finger grippers and broad grey feet. In one full-body three-quarter shot, it bends slightly forward to inspect a large fern frond without touching it, then tilts its rectangular upper body a little to one side. Gentle servo sounds and greenhouse ambience. A completely new leafy glasshouse background. No speech, music, text or cuts.",
"duration": 5,
"resolution": "720p",
"multi_shots": false,
"video_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-2.6/reference-to-video/v1/02/input.mp4"
]
}
}
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,失败时读取 data.error_message。
状态查询端点
GET https://api.vidgo.ai/api/generate/status/{task_id}使用 task_id 查询进度;not_started 或 running 时继续轮询,finished 或 failed 时停止。成功后读取 data.files[].file_url,失败时读取 data.error_message。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "7MP4RU1LZGJT3NOK",
"status": "running",
"created_time": "2026-09-21T17:33:00"
}
}{
"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
}
}端到端完整脚本示例
展开查看在生产环境中具备轮询重试、异常保护和超时处理的完整自动化脚本。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-2.6/reference-to-video",
"input": {
"prompt": "Use the exact yellow robot from the reference video as the sole character. Place it on a stone path inside a daylight fern greenhouse. Preserve the mustard rectangular torso, single turquoise eye, short arms with two-finger grippers and broad grey feet. In one full-body three-quarter shot, it bends slightly forward to inspect a large fern frond without touching it, then tilts its rectangular upper body a little to one side. Gentle servo sounds and greenhouse ambience. A completely new leafy glasshouse background. No speech, music, text or cuts.",
"duration": 5,
"resolution": "720p",
"multi_shots": false,
"video_urls": [
"https://cdn.vidgo.ai/apis/models/alibaba/wan-2.6/reference-to-video/v1/02/input.mp4"
]
}
}
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 对象)
向 /api/generate/submit 提交 POST 请求时,input 内部所支持的参考生视频参数:
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| prompt | string | 是 | — | 字符串。校验前去除首尾空白,支持 1–5,000 个 Unicode 字符。 |
| video_urls | array<string> | 是 | — | 数组,包含 1–10 个 HTTP(S) 视频 URL。支持 MP4、MOV、MKV,每个最大 10MiB,由 PoYo 校验远程文件;不额外限制输入视频时长。 |
| duration | integer | 否 | 5 | 整数。输出时长支持 5、10 秒。 |
| resolution | string | 否 | 720p | 输出分辨率:720p 或 1080p。 |
| multi_shots | boolean | 否 | — | 可选布尔值。省略时不指定上游设置;体验区初始为 false。不额外计费。 |
响应字段(查询结果)
通过 GET /api/generate/status/{task_id} 轮询获取的任务详情:
| 字段 | 类型 | 描述 |
|---|---|---|
| code | integer | 业务响应状态码,200 表示成功。 |
| data.task_id | string | 异步任务全局唯一流水号。 |
| data.status | string | 任务执行阶段:not_started(排队中)、running(生成中)、finished(已完成)、failed(失败)。 |
| data.files | array | 生成成功时包含的成片文件列表,每项含 file_url 与 file_type。 |
| data.error_message | string | null | 任务执行异常时的具体错误描述。 |
任务生命周期
客户端应根据 status 字段判断任务进度,达到 finished 或 failed 终态时立即终止轮询:
not_started任务已接收,等待执行。
running正在生成。
finished生成完成,从 data.files 获取视频 URL。
failed生成失败,请查看 data.error_message,已扣积分按现有流程返还。
轮询与异常处理
- 轮询频次推荐建议初始轮询间隔设为 2–3 秒,随着任务持续可递增至 5 秒一次,避免过密请求。
- 网络波动与重试若查询网络出现 5xx 或连接超时,不代表任务失败,可稍作休眠后继续重试查询。
- 异步 Webhook 回调支持在提交请求体根层级传递 callback_url,在任务终态时系统将通过 POST 自动推送完整任务结果。
接口规格
| 规格项 | 取值 | 说明 |
|---|---|---|
| 模型 ID | alibaba/wan-2.6/reference-to-video | 在请求根级 model 字段中发送此值。 |
| 时长 | 5, 10s | 默认 5 秒。 |
| 分辨率 | 720p / 1080p | 默认 720p。 |
Wan 2.6 Reference to Video API 常见问题
Wan 2.6 Reference to Video API 是什么?
Wan 2.6 Reference to Video 是阿里巴巴研发的参考视频生成视频模型。它根据 1–10 个参考视频片段与文本提示词生成 5–10 秒、最高 1080p 分辨率的高清动态成片,支持多机位运镜调度与多镜头转换。基于 Diffusion Transformer 时空生成架构,它在深度汲取参考片段运动规律、动作节奏与构图质感的同时,精准构建提示词要求的新场景与主体交互。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Wan 2.6 Reference to Video 可以上传多少个参考视频?
本端点支持输入 1 到 10 个参考视频文件。API 接收 video_urls 数组,支持 MP4、MOV 和 MKV 格式,每个视频文件大小上限为 10MiB,无需严格限制输入视频的时长。
Wan 2.6 Reference to Video 如何提取参考视频的动作?
模型通过时空交叉注意力机制提取参考视频的时序骨骼动态与摄影机运动轨迹。在提示词中结合新角色与环境描述,模型会将捕捉到的动作律动平滑赋予新画面,实现高水准的动势迁移。
Wan 2.6 Reference to Video 的输出时长支持哪些档位?
输出时长支持 5 秒和 10 秒(默认 5 秒)。由于参考视频需要更密集的多帧时空特征对齐,本端点专注提供 5 秒与 10 秒的高保真成片输出。
Wan 2.6 Reference to Video 开启多镜头需要额外付费吗?
无需额外付费。开启 multi_shots 参数后,模型会自动根据参考素材的动势与提示词情节规划多视角镜头转换,计费依然严格按时长与分辨率标准执行。
Wan 2.6 Reference to Video 的 1080p 输出清晰度如何?
分辨率设为 1080p 时,模型能输出细节锐利、动态平滑的全高清视频,有效避免了参考低清片段可能带来的重采样模糊,呈现电影级质感。
只有一张静态照片时该使用 Wan 2.6 Reference to Video 吗?
只有单张图片时推荐使用 Wan 2.6 Image to Video 端点。Wan 2.6 Reference to Video 专为提取动态视频中的连续动作与运镜而优化,输入单张图片请选用图生视频端点。