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 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 原生全高清输出能充分保留发丝、水面反光与建筑纹理等细腻材质细节,满足专业成片交付需求。















