API reference

Create Video API: Text, Image and Reference to Video

Submits a render and returns the task at once. Credits are charged when the task is created and given back automatically if it fails.

Get API keyBy the Wan 3 API team ·
POSThttps://api.wan3api.org/v1/videos/generations

Request body

FieldTypeDescription
modelRequiredstringModel id from GET /models.
promptRequiredstringWhat should happen in the video, up to 5000 characters.
modestringtext, frames or reference. Left out, it follows the media you send: frame URLs mean frames, reference URLs mean reference, none means text.
durationintegerOutput length in whole seconds. Defaults to 5 s, clamped into the model's range.
resolutionstringOne of the model's resolutions, such as 480P or 1080P. Defaults to the cheapest.
aspect_ratiostring16:9, 9:16, 1:1 and so on. Ignored in frames mode, where the first frame sets the shape.
first_frame_urlstringFrames mode: public HTTPS image the video starts on.
last_frame_urlstringFrames mode: image the video ends on.
image_urlsstring[]Reference mode: images of the characters, products or style to keep.
video_urlsstring[]Reference mode: clips for motion or camera. Uploaded seconds are billed.
audio_urlsstring[]Reference mode: audio to follow.
callback_urlstringPublic HTTPS URL we POST the finished task to.
curl -X POST "https://api.wan3api.org/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "wan-3",
  "prompt": "A red fox runs through fresh snow at sunrise, slow motion, cinematic",
  "duration": 5,
  "resolution": "480P",
  "aspect_ratio": "16:9"
}'

Modes

  • text — Text to video: only a prompt.
  • frames — Image to video: a first frame, and optionally a last frame, plus a prompt for the motion.
  • reference — Reference to video: up to 10 images, 5 clips and 5 audio files the video should stay faithful to (Wan 3.0 and Wan 3.0 Prime).

Image to video

json
{
  "model": "wan-3",
  "prompt": "The camera slowly pushes in as she turns and smiles",
  "duration": 5,
  "resolution": "480P",
  "first_frame_url": "https://example.com/first-frame.jpg"
}

Reference to video

json
{
  "model": "wan-3",
  "prompt": "Image 1 walks through a neon-lit night market, handheld camera",
  "duration": 5,
  "resolution": "480P",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "callback_url": "https://your-app.com/webhooks/video"
}

Media URLs

We download each URL when you submit, so it must be public HTTPS and answer within 20 seconds. Sizes and lengths follow the same limits as uploads in the web app. A URL we can't fetch returns 400 media_unreachable before anything is charged.

Idempotency

Send an Idempotency-Key header (any unique string, up to 255 characters) to make retries safe. A repeat with the same key returns the original task with the header Idempotent-Replayed: true and charges nothing.

Response

200 with the task object. status is processing until the render finishes.

json
{
  "id": "3f1c9a52-6d1e-4c1b-9a77-2f4d8f0c9e10",
  "object": "video.generation",
  "model": "wan-3",
  "mode": "text",
  "status": "processing",
  "progress": 0,
  "prompt": "A red fox runs through fresh snow at sunrise, slow motion, cinematic",
  "duration": 5,
  "resolution": "480P",
  "aspect_ratio": "16:9",
  "video_url": null,
  "credits": 15,
  "refunded": false,
  "error": null,
  "source": "api",
  "created_at": "2026-11-01T08:00:00.000Z",
  "completed_at": null
}

Price

Output seconds times the model's per-second rate for the resolution, plus any reference video seconds at the same rate. Reference images are free. The credits field in the response is the exact amount charged. See Models and pricing for the rates. Models and pricing →

PreviousAuthenticationNextTasks