Use Reference Image 1 for the same explorer, face, helmet and ochre clothing. Use Reference Image 2 for the same brass lantern. Two shots in a limestone cave: first three seconds, a medium-wide shot of her holding the lantern and taking one careful step; last two seconds, cut to a waist-up view as she raises the lantern to illuminate mineral textures. Preserve her identity, outfit and lantern across the cut. Restrained natural movement. No text, lettering, captions, logos, watermarks, brands, advertising or product packaging.
Wan 2.7 Reference to Video API
alibaba/wan-2.7/reference-to-videoWan 2.7 Reference to Video 结合最多 9 张参考图片或参考视频生成 2–10 秒高质量成片,支持 9 宫格分镜输入、多镜头叙事编排以及丰富的画幅选择。它能够在复杂的场景切换与多机位运镜中,持续稳定锁定人物面容、服装与主体风格,避免特征漂移。
拖拽文件、粘贴剪贴板素材,或输入 URL。
2/9 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。
示例
REST API 规格
快速开始
提交任务并查询状态。
第一步:配置 API 鉴权
在控制台创建 API Key,提交请求时附带 Authorization: Bearer <API_KEY>。
- 任务提交端点
- POST
https://api.vidgo.ai/api/generate/submit - 鉴权请求头
- Authorization: Bearer VIDGO_API_KEY
第 2 步:提交任务
POST /api/generate/submit · alibaba/wan-2.7/reference-to-video
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-2.7/reference-to-video",
"input": {
"resolution": "720p",
"duration": 5,
"prompt": "Describe the scene or edit",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://example.com/reference.png"
]
}
}
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": "task-example",
"status": "running",
"created_time": "2026-09-21T08: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
}
}端到端完整脚本示例
展开查看在生产环境中具备轮询重试、异常保护和超时处理的完整自动化脚本。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-2.7/reference-to-video",
"input": {
"resolution": "720p",
"duration": 5,
"prompt": "Describe the scene or edit",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://example.com/reference.png"
]
}
}
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 | 是 | — | 提示词去除首尾空格后最多 5,000 字符;图生视频可不填。 |
| reference_image_urls | array | 否 | — | 最多 9 张有序参考图片,支持 HTTP(S)、Data URI 或 Base64。参考图片或视频至少提供一项。 |
| reference_video_urls | array | 否 | — | 公开 HTTP(S) 参考视频地址数组;参考图片或视频至少提供一项。 |
| aspect_ratio | string | 否 | 16:9 | 16:9、9:16、1:1、4:3 或 3:4,默认 16:9。 |
| resolution | string | 否 | 720p | 720p 或 1080p,默认 720p。 |
| duration | integer | 否 | 5 | 2–10 整数秒,默认 5 秒。 |
| multi_shots | boolean | 否 | — | 可选的多镜头控制,默认不传。 |
| seed | integer | 否 | — | 可选整数,范围为 0–2147483647。 |
| enable_safety_checker | boolean | 否 | — | 可选安全检查设置,默认不传。 |
响应字段(查询结果)
通过 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已就绪
failed失败
轮询与异常处理
- 轮询频次推荐建议初始轮询间隔设为 2–3 秒,随着任务持续可递增至 5 秒一次,避免过密请求。
- 网络波动与重试若查询网络出现 5xx 或连接超时,不代表任务失败,可稍作休眠后继续重试查询。
- 异步 Webhook 回调支持在提交请求体根层级传递 callback_url,在任务终态时系统将通过 POST 自动推送完整任务结果。
接口规格
| 规格项 | 取值 | 说明 |
|---|---|---|
| 模型 | alibaba/wan-2.7/reference-to-video | |
| 分辨率 | 720p / 1080p | 默认 720p |
| 时长 | 2–10 整数秒,默认 5 秒。 |
Wan 2.7 Reference to Video API 常见问题
Wan 2.7 Reference to Video API 是什么?
Wan 2.7 Reference to Video 是阿里通义实验室研发的参考驱动视频生成模型。它能够结合最多 9 张参考图片或参考视频与文本提示词,生成 2 至 10 秒 720p 或 1080p 高清视频,原生支持 9 宫格分镜工作流、多镜头连续叙事以及跨镜头主体一致性保持。基于 Diffusion Transformer 骨干网络与 Wan-VAE 3D 时空因果压缩架构,它在复杂机位调度与多视角切换中深度锁定角色特征与风格基调,有效避免视觉漂移。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Wan 2.7 Reference to Video 最多可以上传多少张参考图片?
Wan 2.7 Reference to Video 支持在 reference_image_urls 数组中传入最多 9 张参考图片。你可以结合多机位角色定妆照、产品实物特写或 9 宫格连环分镜图进行复合指导。
Wan 2.7 Reference to Video 如何利用 9 宫格分镜指导生成?
你可以直接上传包含 9 个画格的故事板图片作为参考。模型能够解析图中的分格构图与情节演进线索,结合文本提示词的时序描述,将分格静帧动态化为连贯完整的视听长镜头。
Wan 2.7 Reference to Video 支持输入参考视频吗?
支持。除了参考图片外,你还可以通过 reference_video_urls 传入参考视频。模型会分析参考视频中的镜头动势、肢体节奏及光影变幻,并迁移到新镜头的生成中。
Wan 2.7 Reference to Video 最长生成时长是多少?
Wan 2.7 Reference to Video 支持 2 至 10 秒之间的任意整秒时长设置,默认时长为 5 秒。适中的时长范围有利于在高强度多主体参考下保证帧率与画质的极高稳定性。
Wan 2.7 Reference to Video 如何在提示词中对应不同参考主体?
在提示词中可以针对不同参考图中的核心特征进行文字指向。模型的注意力层会将文本中的角色、服饰或道具描述精准映射至对应参考图的特征嵌入上。
Wan 2.7 Reference to Video 的 multi_shots 参数起什么作用?
将 multi_shots 设为 true 时,模型会在单一生成片段内智能规划多景别切换或镜头转换,在保持被参考角色外观稳定的同时,呈现更丰富多变的分镜语言。