Pick the Wan 3 input from the clip you have: a written scene, a first frame, reference assets, or a file to continue. One model and one submit endpoint cover those jobs.
Start from the clip you need
This guide shows how to use the Wan 3 video API through TTAPI. Start from the clip: a scene you can write, a still that must open the first frame, reference assets that have to hold, or a file that needs another beat.
Alibaba describes wan3.0-video as an All-in-One model that can generate up to 30 seconds at 30 fps, create dialogue, music, and sound effects, and accept text, images, video, audio, documents, or public web pages as creative input. TTAPI exposes those jobs through the same Wan 3 submission endpoint. A prompt-only request creates text-to-video. Values in input.media select a first frame, first and last frames, multimodal references, or a source video for editing and extension. Check the current TTAPI reference before shipping because input combinations have specific rules.
- Prompt only: text-to-video.
- first_frame or first_frame + last_frame: controlled opening or transition.
- reference_image, reference_video, or reference_audio: reference-guided generation.
- reference_video plus an edit or extension instruction: transform or continue a clip.
Text-to-video: direct a complete scene
Use text-to-video when the scene can begin from a written brief. The published hospital-corridor example describes the location, lighting, actor movement, camera tracking, dialogue, and ambient sound without providing source media.
Write motion and time, not only visual adjectives. Name what enters the frame, how the camera moves, what changes before the ending, and whether the scene needs dialogue or sound. The request below uses the current TTAPI Wan 3 fields and the original catalog prompt.
一段现代悬疑风格的电影感长镜头，整个画面呈现出强烈的淡绿色滤镜风格，营造出一种基于淡绿色系的清冷氛围。在散发着冰冷白光的荧光灯下，空无一人的医院走廊呈现出低饱和的色彩与极高对比的光影关系，锐利且非人情化。镜头从护士台后方开始，一名身穿墨绿色夹克的女子猛地从走廊尽头的门后冲入，沿着对称的中心线向镜头快速跑来，摄影机流畅地向后移动。她的脚步声急促而响亮，口中焦急地呼喊。最终，她冲到台前，双手用力拍在台面上，绝望地环顾四周，发出几近崩溃的求助呐喊，声音在只有微弱设备嗡鸣的寂静中回荡。
curl --request POST \
--url 'https://api.ttapi.io/wan/api/v1/services/aigc/video-generation/video-synthesis' \
--header "TT-API-KEY: $TTAPI_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wan3.0-video",
"input": {
"prompt": "一段现代悬疑风格的电影感长镜头，整个画面呈现出强烈的淡绿色滤镜风格，营造出一种基于淡绿色系的清冷氛围。在散发着冰冷白光的荧光灯下，空无一人的医院走廊呈现出低饱和的色彩与极高对比的光影关系，锐利且非人情化。镜头从护士台后方开始，一名身穿墨绿色夹克的女子猛地从走廊尽头的门后冲入，沿着对称的中心线向镜头快速跑来，摄影机流畅地向后移动。她的脚步声急促而响亮，口中焦急地呼喊。最终，她冲到台前，双手用力拍在台面上，绝望地环顾四周，发出几近崩溃的求助呐喊，声音在只有微弱设备嗡鸣的寂静中回荡。"
},
"parameters": {
"resolution": "1080P",
"ratio": "16:9",
"duration": 10,
"audio": true,
"seed": 12345,
"prompt_extend": true,
"watermark": false
}
}'Reference-to-video: coordinate five source images
Use reference-to-video when multiple supplied assets define the characters, objects, space, or style. The heritage-headwear example uses five reference images and a timed direction for centered portraits, subtle head movement, ornament motion, and consistent card-flip transitions.
Reference images are addressed in prompt order as Image 1, Image 2, and so on. Keep that order stable when constructing input.media. The example request pattern below uses the five existing catalog references; consult the TTAPI reference for current limits and valid media combinations.
参考上传的5张关键帧图片，生成一支10秒、16:9横版的国风人物头饰展示短视频。整体风格延续参考视频的节奏与展示逻辑，画面精致、干净、克制，带有时尚国风与中式视觉设计感。5位人物按照上传顺序依次出场，人物始终固定在画面正中央，构图稳定，不要人物跑位，不要大幅运镜，不要夸张肢体动作。每位人物停留约2秒，主要动态为轻微左右摇头、缓慢偏头、微微抬颌或回正，让头饰得到充分展示。头饰上的流苏、花朵、喜鹊、纸鸢、蝴蝶等装饰可以有轻微摆动或颤动，背景中的中式纹样如祥云、亭台楼阁、山水纹样保持相对静止，仅有极轻微的呼吸感或视差感。 人物之间的切换方式要统一为“水平翻牌式切换”：当前人物画面像一张竖立在中心的卡片，围绕竖直中轴做平滑的水平翻转，翻到侧面时短暂变窄，随后下一位人物从翻转的另一面自然出现，形成连续的卡牌翻面效果。切换过程干净利落、平滑顺畅，节奏清晰，不要飞散，不要缩放乱跳，不要人物从边缘飞入。切换时人物位置不能偏移，始终保持中心对齐，像在同一个展示台上不断翻牌更换不同人物。 每一位人物的单独动态要求如下：人物保持半身肖像式展示，眼神自然，表情平静高级，身体整体稳定，只有头部轻微向左偏转再回正，或向右偏转再回正，动作幅度小而优雅，用来展示头饰层次。耳饰、流苏、花枝、鸟羽、纸鸢细节可以随动作产生轻微延迟摆动，增强精致感。不要说话，不要夸张眨眼，不要大笑，不要大幅度扭身。 整体镜头语言以固定镜头为主，可有极轻微缓慢推进，营造高级海报动态感，但不能破坏人物始终居中的展示效果。视频整体节奏是“停留展示—水平翻牌—停留展示—水平翻牌”，重复5位人物，最终在最后一位人物上稳定停留结束。 分镜时间轴版 0s - 2s 第一位人物居中展示。 人物轻微将头从正面偏向一侧，再缓慢回正，展示头顶花朵、喜鹊与流苏头饰。 流苏和小装饰轻微摆动，背景纹样保持稳定。 2s - 2.4s 进入第一次翻牌切换。 当前人物画面围绕竖直中轴做水平翻转，像卡片翻面一样，翻到最窄处后自然切换到下一位人物。 翻转时人物仍固定在中心。 2.4s - 4.4s 第二位人物居中展示。 侧脸人物可做轻微抬颌、微小回头或轻轻转回一点，再停住，突出纸鸢、花朵和喜鹊头饰。 花瓣或小装饰可以极轻微漂浮。 4.4s - 4.8s 第二次翻牌切换。 同样采用水平翻牌式过渡，干净利落，不要多余特效。 4.8s - 6.8s 第三位人物居中展示。 人物轻微左右摇头，小幅展示夸张头饰的不同层次。 头饰中的鸟、纸鸢、流苏可有细微摆动，背景云纹轻微呼吸感。 6.8s - 7.2s 第三次翻牌切换。 继续保持统一的中心翻牌节奏。 7.2s - 8.6s 第四位人物居中展示。 人物轻微偏头，露出头饰正面与侧向层次，动作幅度小，精致克制。 8.6s - 9.0s 第四次翻牌切换。 水平翻转，人物不偏移，节奏平稳。 9.0s - 10s 第五位人物居中展示并作为结尾。 人物轻微抬头或缓慢转头回正，头饰小元素轻轻晃动。 最后稳定停住，定格结束。 不要人物走动，不要人物缩放漂移，不要头饰变形，不要人物位置变化，不要背景乱飞，不要复杂粒子，不要夸张镜头旋转，不要卡顿，不要多人同屏。
curl --request POST \
--url 'https://api.ttapi.io/wan/api/v1/services/aigc/video-generation/video-synthesis' \
--header "TT-API-KEY: $TTAPI_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wan3.0-video",
"input": {
"prompt": "参考上传的5张关键帧图片，生成一支10秒、16:9横版的国风人物头饰展示短视频。整体风格延续参考视频的节奏与展示逻辑，画面精致、干净、克制，带有时尚国风与中式视觉设计感。5位人物按照上传顺序依次出场，人物始终固定在画面正中央，构图稳定，不要人物跑位，不要大幅运镜，不要夸张肢体动作。每位人物停留约2秒，主要动态为轻微左右摇头、缓慢偏头、微微抬颌或回正，让头饰得到充分展示。头饰上的流苏、花朵、喜鹊、纸鸢、蝴蝶等装饰可以有轻微摆动或颤动，背景中的中式纹样如祥云、亭台楼阁、山水纹样保持相对静止，仅有极轻微的呼吸感或视差感。\n\n人物之间的切换方式要统一为“水平翻牌式切换”：当前人物画面像一张竖立在中心的卡片，围绕竖直中轴做平滑的水平翻转，翻到侧面时短暂变窄，随后下一位人物从翻转的另一面自然出现，形成连续的卡牌翻面效果。切换过程干净利落、平滑顺畅，节奏清晰，不要飞散，不要缩放乱跳，不要人物从边缘飞入。切换时人物位置不能偏移，始终保持中心对齐，像在同一个展示台上不断翻牌更换不同人物。\n\n每一位人物的单独动态要求如下：人物保持半身肖像式展示，眼神自然，表情平静高级，身体整体稳定，只有头部轻微向左偏转再回正，或向右偏转再回正，动作幅度小而优雅，用来展示头饰层次。耳饰、流苏、花枝、鸟羽、纸鸢细节可以随动作产生轻微延迟摆动，增强精致感。不要说话，不要夸张眨眼，不要大笑，不要大幅度扭身。\n\n整体镜头语言以固定镜头为主，可有极轻微缓慢推进，营造高级海报动态感，但不能破坏人物始终居中的展示效果。视频整体节奏是“停留展示—水平翻牌—停留展示—水平翻牌”，重复5位人物，最终在最后一位人物上稳定停留结束。\n\n分镜时间轴版\n0s - 2s\n\n第一位人物居中展示。\n人物轻微将头从正面偏向一侧，再缓慢回正，展示头顶花朵、喜鹊与流苏头饰。\n流苏和小装饰轻微摆动，背景纹样保持稳定。\n\n2s - 2.4s\n\n进入第一次翻牌切换。\n当前人物画面围绕竖直中轴做水平翻转，像卡片翻面一样，翻到最窄处后自然切换到下一位人物。\n翻转时人物仍固定在中心。\n\n2.4s - 4.4s\n\n第二位人物居中展示。\n侧脸人物可做轻微抬颌、微小回头或轻轻转回一点，再停住，突出纸鸢、花朵和喜鹊头饰。\n花瓣或小装饰可以极轻微漂浮。\n\n4.4s - 4.8s\n\n第二次翻牌切换。\n同样采用水平翻牌式过渡，干净利落，不要多余特效。\n\n4.8s - 6.8s\n\n第三位人物居中展示。\n人物轻微左右摇头，小幅展示夸张头饰的不同层次。\n头饰中的鸟、纸鸢、流苏可有细微摆动，背景云纹轻微呼吸感。\n\n6.8s - 7.2s\n\n第三次翻牌切换。\n继续保持统一的中心翻牌节奏。\n\n7.2s - 8.6s\n\n第四位人物居中展示。\n人物轻微偏头，露出头饰正面与侧向层次，动作幅度小，精致克制。\n\n8.6s - 9.0s\n\n第四次翻牌切换。\n水平翻转，人物不偏移，节奏平稳。\n\n9.0s - 10s\n\n第五位人物居中展示并作为结尾。\n人物轻微抬头或缓慢转头回正，头饰小元素轻轻晃动。\n最后稳定停住，定格结束。\n不要人物走动，不要人物缩放漂移，不要头饰变形，不要人物位置变化，不要背景乱飞，不要复杂粒子，不要夸张镜头旋转，不要卡顿，不要多人同屏。",
"media": [
{
"type": "reference_image",
"url": "https://cdn-static.picnext.ai/20260826175422-d5ca9c8d.png"
},
{
"type": "reference_image",
"url": "https://cdn-static.picnext.ai/20260826175422-0e67eba6.png"
},
{
"type": "reference_image",
"url": "https://cdn-static.picnext.ai/20260826175425-665db377.png"
},
{
"type": "reference_image",
"url": "https://cdn-static.picnext.ai/20260826175425-42aad73f.png"
},
{
"type": "reference_image",
"url": "https://cdn-static.picnext.ai/20260826175425-b23b5bcc.png"
}
]
},
"parameters": {
"resolution": "720P",
"ratio": "adaptive",
"duration": 10,
"audio": true,
"prompt_extend": true,
"watermark": false
}
}'Image-to-video: animate a controlled first frame
Use first-frame image-to-video when the opening composition already exists and the job is to add motion. The vertical ink-wash example starts from one supplied swordsman image, then directs camera movement, attackers, combat beats, ink effects, and an ending pose over a timed sequence.
Set the media type to first_frame when the source must become the opening frame rather than a looser visual reference. Alibaba recommends adaptive ratio for frame-guided requests so the output follows the input composition.
(0:00 - 0:03) 运镜：中景。 画面：沿用 @Image1 的水墨竹林场景。头戴斗笠、身着墨色长袍的刀客，其剪影伫立在浓雾环绕、竹影婆娑的中心。 动作：刀客左手轻按刀柄，竹叶随风飘落。 氛围：寂静，压抑，水墨晕染的颗粒感清晰可见。 (0:03 - 0:08) 剧情引入，运镜：特写。 剧情：刀客察觉杀气。 画面：镜头快速推进到刀客斗笠下的特写。 细节：斗笠边缘露出一双凌厉、决绝的眼睛，眼神如刀。水墨晕染的“汗珠”从额头滑落。 动作：刀客右手缓缓握紧刀柄，指关节泛白。竹叶飘落的速度加快。 (0:08 - 0:13) 运镜：快速环绕。 画面：镜头以刀客为中心快速环绕。 剧情：两名同样是水墨剪影的刺客从竹林深处杀出，手持双钩和短刃。 细节：刺客的动作也是水墨笔触构成的，如墨迹流动。镜头快速掠过刺客的身影，强调速度感。 (0:13 - 0:18) 运镜：手持感，高速捕捉。 打斗：刀客猛然拔刀，刀光是一道纯白色的水墨裂痕。刺客双钩攻来。 细节： 一击：刀客回身一斩，刀刃与刺客双钩碰撞，迸发出无数黑白相间、带有书法感的火花和墨点。 二击：刀客虚晃一枪，利用竹竿弹射，从高处劈下。刺客翻滚躲避。竹竿被打断，化作飞散的墨痕。 三击：刀客刀尖直指另一刺客咽喉，刺客以短刃格挡，镜头捕捉刀刃与短刃摩擦时细微的墨迹崩裂细节。 **(0:18 - 0:20) 运镜：慢镜头至定格。** * **画面：** 刀客的刀停在刺客颈侧，刺客凝固。 * **细节：** 刀客的斗笠在打斗中略微倾斜。竹林归于平静，更多竹叶飞舞。 * **氛围：** 镜头慢慢拉远，回到中景，定格在刀客收刀、刺客倒地的画面。 * **文字（可选）：** 画面下方显现水墨风文字：“江湖，不过一笔勾销。” **风格说明：** 整个过程保持 `image_0.png` 的高度黑白、水墨画风格，动作必须有毛笔触感，速度要快，细节要足（墨滴、火花、墨痕裂口）。
curl --request POST \
--url 'https://api.ttapi.io/wan/api/v1/services/aigc/video-generation/video-synthesis' \
--header "TT-API-KEY: $TTAPI_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "wan3.0-video",
"input": {
"prompt": "(0:00 - 0:03) 运镜：中景。\n画面：沿用 @Image1 的水墨竹林场景。头戴斗笠、身着墨色长袍的刀客，其剪影伫立在浓雾环绕、竹影婆娑的中心。\n动作：刀客左手轻按刀柄，竹叶随风飘落。\n氛围：寂静，压抑，水墨晕染的颗粒感清晰可见。\n\n(0:03 - 0:08) 剧情引入，运镜：特写。\n\n剧情：刀客察觉杀气。\n画面：镜头快速推进到刀客斗笠下的特写。\n细节：斗笠边缘露出一双凌厉、决绝的眼睛，眼神如刀。水墨晕染的“汗珠”从额头滑落。\n动作：刀客右手缓缓握紧刀柄，指关节泛白。竹叶飘落的速度加快。\n\n(0:08 - 0:13) 运镜：快速环绕。\n\n画面：镜头以刀客为中心快速环绕。\n剧情：两名同样是水墨剪影的刺客从竹林深处杀出，手持双钩和短刃。\n细节：刺客的动作也是水墨笔触构成的，如墨迹流动。镜头快速掠过刺客的身影，强调速度感。\n\n(0:13 - 0:18) 运镜：手持感，高速捕捉。\n\n打斗：刀客猛然拔刀，刀光是一道纯白色的水墨裂痕。刺客双钩攻来。\n细节：\n一击：刀客回身一斩，刀刃与刺客双钩碰撞，迸发出无数黑白相间、带有书法感的火花和墨点。\n二击：刀客虚晃一枪，利用竹竿弹射，从高处劈下。刺客翻滚躲避。竹竿被打断，化作飞散的墨痕。\n三击：刀客刀尖直指另一刺客咽喉，刺客以短刃格挡，镜头捕捉刀刃与短刃摩擦时细微的墨迹崩裂细节。\n\n\n\n**(0:18 - 0:20) 运镜：慢镜头至定格。**\n\n* **画面：** 刀客的刀停在刺客颈侧，刺客凝固。\n* **细节：** 刀客的斗笠在打斗中略微倾斜。竹林归于平静，更多竹叶飞舞。\n* **氛围：** 镜头慢慢拉远，回到中景，定格在刀客收刀、刺客倒地的画面。\n* **文字（可选）：** 画面下方显现水墨风文字：“江湖，不过一笔勾销。”\n\n**风格说明：** 整个过程保持 `image_0.png` 的高度黑白、水墨画风格，动作必须有毛笔触感，速度要快，细节要足（墨滴、火花、墨痕裂口）。",
"media": [
{
"type": "first_frame",
"url": "https://cdn-static.picnext.ai/20260826175439-dd017da0.png"
}
]
},
"parameters": {
"resolution": "720P",
"ratio": "adaptive",
"duration": 20,
"audio": true,
"prompt_extend": true,
"watermark": false
}
}'Video extension: continue an existing scene
Use a reference video with an extension instruction when an existing clip needs a new beat before or after its current action. The tea-house example continues a period negotiation while preserving the two characters, table setting, dialogue rhythm, and ambient scene.
Describe where the extension belongs, which identities and props must remain stable, and what narrative action should happen next. For editing or extension, the official guide recommends adaptive ratio and describes smart duration behavior; use the current TTAPI request reference for supported parameters.
将视频1延长15s。角色A为梳背头、穿深灰色中式长衫、左手腕佩戴棕色佛珠手串的男人，角色B为穿深色中式长衫的男人。角色B缓缓放下茶碗，目光微沉，用指尖轻叩桌面两下，不紧不慢说"价钱好讲，但货要几时到埠，你要畀个准数我。"角色A笑容不减，端起盖碗刮了刮茶沫。角色A呷一口茶，将茶碗搁回茶托，身体前倾压低声音，佛珠随手势轻晃，语气笃定"最迟月底，码头嗰边我已经打点好晒，一船货齐齐整整运到你仓库门口。"说罢右手掌心朝下往桌面一按，目光直视角色B。角色B沉吟片刻，视线扫向窗外"萬安當"牌匾，竹帘被街上微风轻轻掀起。他转回头，嘴角浮起笑意，拿起盖碗朝角色A微微一举，"好，月底交货，我等你好消息。"两人相视而笑。保持民国商战片的沉稳调性，对话节奏从容，茶馆环境音低沉衬底。
Submit once, then retrieve the asynchronous result
Every workflow above submits an asynchronous Wan 3 job. Keep the returned task identifier with the prompt, media list, model, resolution, ratio, and requested duration. An accepted submission means processing has started; it does not mean the MP4 is ready.
Use the task-result endpoint with a bounded polling interval, or the currently documented callback behavior when it fits your application. Stop polling on success, failure, or a client timeout. Download completed files promptly instead of treating a generated URL as permanent storage.
curl --request GET \
--url "https://api.ttapi.io/wan/api/v1/tasks/$TASK_ID" \
--header "TT-API-KEY: $TTAPI_KEY"- Keep the API key on the server.
- Persist the task ID before leaving the submit flow.
- Handle pending, completed, failed, and timeout states.
- Review picture, motion, audio, identity, and text before approving the result.
Open the Wan 3.0 Video API.
Continue from the model page, then follow the current video API documentation.
