A plump raccoon wearing a tiny translucent yellow rain poncho with the hood up stands at a flooded brick alley intersection at blue hour. Puddles cover the cobblestones. Several folded paper boats float in the largest puddle like tiny vehicles. The raccoon holds one autumn maple leaf as a conductor baton and directs the paper boats: first pointing left, then sweeping right, as if managing puddle traffic. Tiny raindrops tap the poncho. Camera: one continuous five-second waist-height lateral tracking shot moving left to right, staying parallel to the raccoon, gentle handheld sway, no cuts. Synchronized audio: steady rain on puddles, raccoon chitters, one distant bicycle bell. No readable text, letters, numbers, captions, labels, logos, brands, watermarks, advertisements, posters, UI screens, or product packaging. No people.
Wan 3.0 Text-to-Video API
alibaba/wan-3.0/text-to-videoWan 3.0(Text-to-Video)将文本提示词转化为 480p 至 1080p 高清视频,支持 2–30 秒单次连续生成、原生音画同步和多画幅构图。它能够根据文字指令稳定呈现面部微表情与复杂运镜,同时实现动作与环境声效的自然匹配。
输入
输出
已就绪继续使用
示例
REST API 规格
快速开始
使用 API Key 提交文生视频请求,并获取所选分辨率的视频结果。
第一步:配置 API 鉴权
在控制台申请 API Key,并在每个 HTTP 请求头中携带 Authorization: Bearer <API_KEY> 进行身份验证。
- 任务提交端点
- POST
https://api.vidgo.ai/api/generate/submit - 鉴权请求头
- Authorization: Bearer VIDGO_API_KEY
第二步:提交文生视频任务
向 /api/generate/submit 端点发起 POST 请求,指定 model 为 alibaba/wan-3.0/text-to-video,并在 input 中填入 prompt 及可选参数。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "alibaba/wan-3.0/text-to-video",
"input": {
"prompt": "A plump raccoon wearing a tiny translucent yellow rain poncho with the hood up stands at a flooded brick alley intersection at blue hour. Puddles cover the cobblestones. Several folded paper boats float in the largest puddle like tiny vehicles. The raccoon holds one autumn maple leaf as a conductor baton and directs the paper boats: first pointing left, then sweeping right, as if managing puddle traffic. Tiny raindrops tap the poncho. Camera: one continuous five-second waist-height lateral tracking shot moving left to right, staying parallel to the raccoon, gentle handheld sway, no cuts. Synchronized audio: steady rain on puddles, raccoon chitters, one distant bicycle bell. No readable text, letters, numbers, captions, labels, logos, brands, watermarks, advertisements, posters, UI screens, or product packaging. No people.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"audio": true,
"enable_safety_checker": true
}
}
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-wan30-t2v-987214",
"status": "running",
"created_time": "2026-09-16T08:30: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-3.0/text-to-video",
"input": {
"prompt": "A plump raccoon wearing a tiny translucent yellow rain poncho with the hood up stands at a flooded brick alley intersection at blue hour. Puddles cover the cobblestones. Several folded paper boats float in the largest puddle like tiny vehicles. The raccoon holds one autumn maple leaf as a conductor baton and directs the paper boats: first pointing left, then sweeping right, as if managing puddle traffic. Tiny raindrops tap the poncho. Camera: one continuous five-second waist-height lateral tracking shot moving left to right, staying parallel to the raccoon, gentle handheld sway, no cuts. Synchronized audio: steady rain on puddles, raccoon chitters, one distant bicycle bell. No readable text, letters, numbers, captions, labels, logos, brands, watermarks, advertisements, posters, UI screens, or product packaging. No people.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"audio": true,
"enable_safety_checker": true
}
}
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–20,000 字符。 |
| 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–2,147,483,647),固定种子有助于重现类似走势。 |
| enable_safety_checker | boolean | 否 | true | 是否开启安全审查过滤。 |
响应字段(查询结果)
通过 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任务已成功提交入队,正等待 GPU 计算节点调度。
running计算节点正在执行 Diffusion Transformer 视频降噪与音轨合成计算。
finished视频已生成并上传持久化存储,可从 data.files[0].file_url 获取播放及下载地址。
failed任务因参数校验不通过或安全合规策略终止,读取 data.error_message 获知原因。
轮询与异常处理
- 轮询频次推荐建议初始轮询间隔设为 2–3 秒,随着任务持续可递增至 5 秒一次,避免过密请求。
- 网络波动与重试若查询网络出现 5xx 或连接超时,不代表任务失败,可稍作休眠后继续重试查询。
- 异步 Webhook 回调支持在提交请求体根层级传递 callback_url,在任务终态时系统将通过 POST 自动推送完整任务结果。
接口规格
| 规格项 | 取值 | 说明 |
|---|---|---|
| 模型标识 | alibaba/wan-3.0/text-to-video | 请求体 model 字段传递的 API 调用路由标识。 |
| 输入模式 | 纯文本提示词 | 通过 prompt 描述主体、动作、运镜、光影与音效设计。 |
| 输出规格 | 30 fps / MP4 (H.264) | 高兼容性 MP4 视频容器,内嵌 AAC 原生音轨。 |
| 单次时长 | 2–30 秒 | 支持在 2 到 30 秒闭区间内按整秒自由设置生成时长。 |
| 原生分辨率 | 480p / 720p / 1080p | 可选标清、高清与全高清三档原生输出分辨率,默认 720p。 |
Wan 3.0 Text-to-Video
Wan 3.0 Text-to-Video 由阿里通义实验室开发,根据纯文本提示词直接生成带原生同步音轨的连续高清视频。在提示词中分别规划主体动作、场景发展与镜头运动,即可在单次生成中获得 2–30 秒、最高 1080p 分辨率的动态成片。
为什么选择此模式?
纯文字驱动成片直接通过自然语言构筑主体形象、空间布景与动态故事,无需预先制作或上传任何静态起始图片。
原生音画联合生成依托 Diffusion Transformer 架构直接输出视频与同步音频,自然匹配人物对白、环境声场与动作音效。
长达 30 秒连续动态支持 2–30 秒整秒时长设定,在单次生成中保持角色面部特征稳定,连贯演绎多阶段戏剧动作。
专业运镜与构图控制支持推拉摇移、跟拍与航拍等镜头语言描述,并提供横屏、竖屏、方形及自适应多画幅输出。
最高 1080p 高清输出提供 480p、720p 与 1080p 原生分辨率选项,充分保留光影质感与材质细节,满足专业展示需求。
参数说明
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 字符串。详细描述主体、动作、镜头运动、光影氛围与音效设计;去除首尾空格后支持 1–20,000 个字符。 |
| duration | 可选 | 整数。设置生成视频的时长,取值范围为 2–30 秒;体验区默认预设为 5 秒。 默认值 5 |
| resolution | 可选 | 字符串。指定输出视频的分辨率规格;可选 480p、720p(默认)或 1080p。 默认值 720p480p1080p |
| aspect_ratio | 可选 | 字符串。控制画面的长宽比例;支持 adaptive(自适应,默认)、16:9、4:3、1:1、3:4 和 9:16。 默认值 adaptive16:94:31:13:49:16 |
| audio | 可选 | 布尔值。控制是否同时生成与画面匹配的原生同步音频;默认为 true,与无音频输出同价。 默认值 truefalse |
| seed | 可选 | 整数。随机数种子,取值范围为 0–2,147,483,647;固定种子有助于复现相似构图与运镜走势。 |
| enable_safety_checker | 可选 | 布尔值。开启后对生成内容执行安全合规校验;默认为 true。 默认值 truefalse |
使用方法
定义主体与世界观在提示词第一句交代角色外貌、核心道具与所处环境背景,例如:赛博朋克雨夜街道中站立的穿黑色风衣的年轻侦探。
按时序组织动作节拍按照时间发展顺序依次描写动作变化,使用“首先、随后、最后”或具体秒数组织行为,例如:他抬头观察招牌,随即快步走进小巷。
单独补充镜头轨迹与运镜用独立句子指明摄影机景别与运动路线,例如:平视中景缓慢推近,镜头随角色步伐侧向跟拍并微仰角展现建筑高耸感。
细化光线氛围与声音提示补充色彩基调(如冷蓝色调与霓虹反光),并描述期待的声音元素,例如:伴随清晰的皮鞋踩水脚步声与远处隐约的雷鸣。
配置规格与参数根据发布平台选择合适的分辨率(推荐 720p 或 1080p)、目标画面比例(横屏 16:9 或竖屏 9:16)以及所需生成时长(2–30 秒)。
提交生成并检视成片点击运行提交异步任务,通过右侧预览面板或查询接口查看结果,画面动作与原生音效将同步呈现。
计费说明
Wan 3.0 Text-to-Video 按实际生成的成片秒数计费,费率仅由选择的分辨率决定;开启或关闭音频不影响计费费率(1 积分 = $0.005)。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 480p | 10 积分 / 输出秒($0.05 / 秒) | 基础高清规格。生成默认 5 秒为 50 积分($0.25);生成最长 30 秒为 300 积分($1.50)。 |
| 720p(默认) | 20 积分 / 输出秒($0.10 / 秒) | 主流高清规格。生成默认 5 秒为 100 积分($0.50);生成最长 30 秒为 600 积分($3.00)。 |
| 1080p | 40 积分 / 输出秒($0.20 / 秒) | 旗舰全高清规格。生成默认 5 秒为 200 积分($1.00);生成最长 30 秒为 1200 积分($6.00)。 |
适用场景
商业广告创意预演将文字脚本与摄影分镜直接转化为动态概念样片,在实拍前直观检验运镜节奏与氛围构思。
短剧与影视故事板构思根据小说章节或剧本片段生成 2–30 秒连续剧情镜头,为导演和主创团队提供直观表演与视效参考。
全渠道社交媒体内容制作同一文本创意灵活选择 16:9、9:16 或 1:1 画幅,生成配有环境音效的高清动态短视频。
游戏与概念世界动态设定把天马行空的幻想生物、科幻飞船或自然风光描述转化为生动细腻的动态概念演示。
创作技巧
- 提示词分层书写骨架:建议按“主体外观与环境设定 → 连续动作时序 → 摄影机运镜与景别 → 光影氛围与同期音效”的层级组织提示词。
- 主体运动与镜头运动解耦:将角色的动作(如奔跑、转身)与摄影机的运动(如推近、环绕摇摄)写在不同分句中,有助于画面轨迹更加清晰明确。
- 合理分配长时长的动作密度:生成 10 秒以上视频时,可以使用“第 0–5 秒……随后在第 6–10 秒……”的分段提示词,指导模型循序渐进展现故事发展。
- 善用声音描述激活原生音效:在提示词中自然加入声音特征(如清脆的风铃声、低沉的汽车引擎轰鸣、带有回音的对话),模型会自动合成对应音效。
- 循序渐进的调优策略:首次构思时建议先使用 5 秒 720p 快速验证画面动态与动作走向,满意后再调高至 1080p 和更长秒数输出成片。
注意事项
- 纯文本输入模式:本端点专为文字生成视频设计,仅接收 prompt 文本,无需且不支持传入图片或参考媒体文件。
- 整秒时长设定:duration 参数接受 2–30 之间的整数秒,请勿传递浮点数或超出该区间的数值。
- 异步任务处理机制:API 采用异步工作流,POST 提交成功后立即返回 task_id,随后通过 GET 状态接口轮询或配置回调获取最终视频地址。
Wan 3.0 Text-to-Video API — 常见问题
Wan 3.0 Text-to-Video API 是什么?
Wan 3.0 Text-to-Video 是阿里通义实验室研发的文本生成视频模型。它根据纯文本提示词直接生成最长 30 秒、最高 1080p 分辨率、包含原生同步音轨的高清视频,支持专业镜头运镜与多画幅构图。基于 Diffusion Transformer 与 Flow Matching 架构,它在稳定呈现人物微表情与复杂运镜的同时,实现动作节拍与环境声效的自然匹配。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Wan 3.0 文生视频单次生成可以达到 30 秒吗?
可以。模型支持在 2 到 30 秒闭区间内任意指定整秒时长(体验区默认预设为 5 秒)。在长达 30 秒的连续动态中,能够保持角色面部特征与场景空间稳定,连贯演绎多阶段戏剧动作。
Wan 3.0 文生视频的音轨是后配的还是原生生成的?
是原生生成的。音轨由底层扩散网络随画面同步去噪生成,而非外部模型拼接。当保持 audio 参数默认开启时,模型会根据提示词中的动作与环境描写,自动合成紧密贴合画面的环境底噪、碰撞脚步与拟真氛围声。
Wan 3.0 文生视频支持生成纯静音视频吗?
支持。若只需要纯静音视频素材,只需将请求中的 audio 参数设为 false。开启或关闭音频不会改变计费标准。
如何让 Wan 3.0 文生视频在长镜头中保持角色面部稳定?
建议在提示词中按时间线清晰划分叙事节拍(如“首先……随后……最终……”),并分别独立描述角色的外观特征与摄影机运动。避免在单句中同时堆叠互相冲突的动作,有助于模型稳定维持角色的面容微表情与身体比例。
Wan 3.0 文生视频的 adaptive 自适应比例如何工作?
当 aspect_ratio 设为 adaptive(默认)时,模型会根据提示词所描绘的场景内容与镜头特征智能适配最和谐的构图画幅。此外,也可显式指定 16:9、4:3、1:1、3:4 或 9:16,直接适配横屏电影或竖屏社交媒体排版。
Wan 3.0 文生视频生成 1080p 成片需要额外参数吗?
不需要。只需在 resolution 参数中指定 1080p(可选 480p、720p 与 1080p)。1080p 原生全高清输出能充分保留发丝、水面反光与建筑纹理等细腻材质细节,满足专业成片交付需求。
