Wan
Wan is Alibaba Cloud’s video model line. Each version generates a clip with a soundtrack from a text prompt, from a still image, or from a set of reference images. Generation is asynchronous. You submit a task, poll it until the status is terminal, then download the clip. The route mirrors Alibaba Cloud’s own API, so the request and response shapes are the provider’s.Best for
- Longer takes. Wan 3.0 holds a shot for up to 30 seconds in one clip.
- Reference-driven scenes. Up to ten reference images carry a subject into new footage instead of animating one frame.
- Draft passes. Wan 3.0 and Wan 3.0 Prime sell a 480P tier that the earlier versions do not.
- Speed grades. Wan 3.0 Prime returns the same capabilities sooner than the standard grade.
Models
Durations are whole seconds. Wan 3.0 and Wan 3.0 Prime use one model ID for all three tasks. The items in
input.media[] select the task. No media item gives text-to-video. A first_frame item gives image-to-video. reference_image items give reference-to-video. Wan 2.7 uses one model ID per task.
Wan 3.0 gives the longest clips and the widest reference set. Use it when a shot has to develop, or when a subject must carry across a new scene. It takes an optional end frame on image-to-video.
Wan 3.0 Prime is the accelerated grade of Wan 3.0. Alibaba Cloud describes it as the high-speed version with capabilities aligned to the standard version. It has the same tasks, tiers, lengths and reference ceiling as Wan 3.0. Use it while you iterate.
Wan 2.7 has a shorter ceiling and a smaller reference set. On image-to-video it takes an optional end frame and a driving audio track.
Endpoints
HappyHorse uses the same two routes and the same body shape.
Request
Send your API key in theX-API-Key header. See Authentication. Set Content-Type: application/json. The examples also send a User-Agent header that names your application.
string
required
The model ID from the table above. On Wan 3.0 and Wan 3.0 Prime the same ID serves every task.
object
required
The prompt and the media items.
object
The generation controls. All tasks read all three fields.
Response
Submit
A 200 status means that the provider accepted the task. It does not mean that the clip is ready.object
required
Poll
string
required
PENDING or RUNNING while the task runs. SUCCEEDED, FAILED or CANCELED when it ends. Poll until you read one of the three terminal values.string
The URL of the clip. Present only when
task_status is SUCCEEDED. The task ID and the URL expire after 24 hours. Download the clip as soon as the task succeeds.string
The failure code. Present when the task failed.
string
The failure message. Read it before you resubmit.
Example
Submit, poll, download. Swap themodel value for the version you want.
first_frame item to input.media[]. To carry a subject into a new scene, add reference_image items instead. A first frame and a reference set are separate tasks. The bodies below replace the submit body in the example.
Tips
- Say what moves and how the camera follows it. The prompt drives both, and motion is what the model has to generate.
- Name the sounds you want in the prompt when audio matters. The model scores what it reads.
- Send
resolutionanddurationon every request. The defaults are 1080P and 5 seconds, and 1080P is the most expensive tier. - Draft at 480P on Wan 3.0, then re-run the prompt at the tier and length you need. You are billed per second of output, so a long 1080P draft is the expensive way to test wording.
- Match the model to the job. A first frame fixes the composition. A reference set fixes the subject and lets the scene change.
- Upload the frame at the tier you intend to render. A small source limits what the model can resolve.
- Poll every 5 seconds at first, then back off to 30 seconds. Polls are free and never use a concurrency slot.
Errors and limits
A 200 status on submit means that the provider accepted the task. It does not mean that the task succeeded. A task that fails later ends withtask_status set to FAILED or CANCELED, and output.message explains why. Read the message before you resubmit.
A failed submit returns an HTTP error status. The body carries code, message and request_id. See Error codes.
A 5xx status or a timeout on submit does not tell you whether the task was created. Never resubmit blindly. If the submit returned a task_id, poll it. If it returned nothing, check your credits before you try again.
Alibaba Cloud applies these limits to each reference image:
- 240 to 8,000 pixels on each side
- An aspect ratio no wider than 8:1
- JPEG, JPG, PNG, BMP or WEBP. A transparent channel is not supported.
- Up to 20 MB per file