Wan 3.0 API

The Wan 3.0 API generates videos with the same models, credits and limits as the workspace. Each request acts as your account: it spends your credits, follows your membership, and its videos appear in your history.

The API is REST over HTTPS with JSON bodies. Every URL below is relative to https://wan3.video/api/v1. Videos render asynchronously: you create a video, poll it until its status is completed or failed, then download it. Rendering usually takes a few minutes. Videos made through the API send no completion email.

Call the API from your own server. Browsers cannot call it directly, and an API key in web or app code can be copied and used to spend your credits.

Create a key on the API keys page while signed in. The full key is shown only once, so store it in a secret manager or an environment variable. An account can hold up to 10 active keys; revoke a key there as soon as it may have leaked.

Send the key as a bearer token with every request. A missing, invalid or revoked key returns 401 UNAUTHORIZED.

curl https://wan3.video/api/v1/account \
  -H "Authorization: Bearer $WAN3_API_KEY"

1. Create a five-second 720P video from a prompt. The response is the new video, with status set to processing.

curl https://wan3.video/api/v1/videos \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "w3.0-video",
    "prompt": "A paper boat drifting down a rain-soaked street at dusk, cinematic lighting",
    "resolution": "720P",
    "duration": 5,
    "aspectRatio": "16:9"
  }'

2. Poll the video every 10–15 seconds until it completes or fails.

curl https://wan3.video/api/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $WAN3_API_KEY"

3. Download the MP4. The URL may redirect to our file storage, so follow redirects.

curl -L -o video.mp4 https://wan3.video/api/v1/videos/VIDEO_ID/content \
  -H "Authorization: Bearer $WAN3_API_KEY"

The same flow in Python:

import os
import time
import uuid

import requests

API = "https://wan3.video/api/v1"
KEY = os.environ["WAN3_API_KEY"]


def api(method, path, headers=None, **kwargs):
    response = requests.request(
        method,
        f"{API}{path}",
        headers={"Authorization": f"Bearer {KEY}", **(headers or {})},
        timeout=60,
        **kwargs,
    )
    body = response.json()
    if body["error"]:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    return body["data"]


video = api(
    "POST",
    "/videos",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "w3.0-video",
        "prompt": "A paper boat drifting down a rain-soaked street at dusk",
        "resolution": "720P",
        "duration": 5,
    },
)

while video["status"] == "processing":
    time.sleep(10)
    video = api("GET", f"/videos/{video['id']}")

if video["status"] == "failed":
    raise RuntimeError(video["error"]["message"])

download = requests.get(
    video["videoUrl"], headers={"Authorization": f"Bearer {KEY}"}, timeout=300
)
download.raise_for_status()
with open(f"{video['id']}.mp4", "wb") as file:
    file.write(download.content)

Every JSON response has the same envelope. A success carries { "data": …, "error": null }; a failure carries { "data": null, "error": { "code", "message" } }. Branch on error.code, which is stable; message is meant for people and may change. Some errors add fields, such as the credits a video needs.

Every response also has an X-Request-Id header. Quote it when you contact support about a request.

HTTP/1.1 402 Payment Required
X-Request-Id: 3f1c9a52-6a0e-4c55-9d7e-0f6f1d2b8c41

{
  "data": null,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits for this generation",
    "requiredCredits": 10,
    "availableCredits": 3.5
  }
}

A network error can leave you unsure whether a video was created. Send an Idempotency-Key header with POST /videos, for example a UUID, and retry with the same key: the retry returns the video the first attempt created, with status 200 and an Idempotent-Replayed: true header, instead of starting and charging a second one.

Keys may be 1–255 printable ASCII characters without spaces and are scoped to your account. Use a new key for every new video: reusing one with different parameters returns 422 IDEMPOTENCY_KEY_MISMATCH. When the first attempt was refused before a video existed, for example for lack of credits, a retry with the same key runs again.

Returns the account's credit balance, membership, and how many of its videos are rendering now against the concurrency limit.

{
  "data": {
    "credits": 128.5,
    "membership": {
      "active": true,
      "plan": "pro",
      "expiresAt": "2026-11-06T08:00:00.000Z"
    },
    "activeGenerations": 2,
    "maxActiveGenerations": 20
  },
  "error": null
}

Image-to-video and video edits take files you upload first. Uploading takes three steps: create an upload here, PUT the file to the returned uploadUrl, then complete it. Pass the upload's key when you create a video. Uploads belong to your account and are deleted after seven days.

curl https://wan3.video/api/v1/uploads \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "first-frame.png",
    "contentType": "image/png",
    "bytes": 1048576
  }'

{
  "data": {
    "key": "temp/5f0c…/2026-10-06/7d1e…-first-frame.png",
    "uploadUrl": "https://…r2.cloudflarestorage.com/…",
    "uploadMethod": "PUT",
    "uploadHeaders": { "Content-Type": "image/png" },
    "uploadExpiresAt": "2026-10-06T08:15:00.000Z",
    "expiresAt": "2026-10-13T08:00:00.000Z"
  },
  "error": null
}

Then send the file's bytes to uploadUrl with the method and headers given, within 15 minutes. Do not send your API key to this URL.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --upload-file first-frame.png

Checks the uploaded file against the model's media requirements and returns a video's duration. Creating a video checks its files again, so this step is optional, but it reports a bad file before you create a video. Files are not resized or converted: send media that already meets the requirements.

curl https://wan3.video/api/v1/uploads/complete \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "temp/5f0c…/2026-10-06/7d1e…-first-frame.png",
    "contentType": "image/png",
    "bytes": 1048576
  }'

{
  "data": {
    "key": "temp/5f0c…/2026-10-06/7d1e…-first-frame.png",
    "contentType": "image/png",
    "bytes": 1048576,
    "expiresAt": "2026-10-13T08:00:00.000Z"
  },
  "error": null
}

Videos also return durationSeconds. A file that is missing, differs from the declared type or size, or breaks a media rule returns 400 UPLOAD_INVALID with the reason.

Starts rendering a video and charges its credits. If rendering fails, the credits are refunded automatically. Prompts first pass a content safety review; a refused prompt costs nothing.

curl https://wan3.video/api/v1/videos \
  -H "Authorization: Bearer $WAN3_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b0f6f5e-0c55-4a2b-9a7d-3f1e2d4c5b6a" \
  -d '{
    "model": "w3.0-video",
    "prompt": "The camera slowly pushes in as she turns toward the window",
    "images": [
      { "key": "temp/5f0c…/first-frame.png", "role": "first_frame" }
    ],
    "duration": 5
  }'

{
  "model": "w3.0-video",
  "prompt": "Turn the street into a snowy winter night",
  "videoKey": "temp/5f0c…/source.mp4",
  "images": [{ "key": "temp/5f0c…/style.jpg" }],
  "duration": 5
}

Returns 201 with the new video object, whose status is processing. Common refusals are 402 INSUFFICIENT_CREDITS, 403 MEMBERSHIP_REQUIRED, 422 NSFW_PROMPT and 429 ACTIVE_GENERATION_LIMIT; see error codes.

Returns the video object. For a video that is still processing, this also asks the provider for its latest progress. Poll no more often than every 5 seconds.

Returns your videos, newest first.

curl "https://wan3.video/api/v1/videos?limit=20&status=completed" \
  -H "Authorization: Bearer $WAN3_API_KEY"

{
  "data": {
    "videos": [ { "id": "video_…", "status": "completed", … } ],
    "nextCursor": "video_1759737600000_4f2a9c1e"
  },
  "error": null
}

nextCursor is null on the last page.

Returns the completed video as an MP4 file. Archived videos answer with a 307 redirect to our file storage, so follow redirects; the file URL itself needs no key. Range requests are supported. A video that has not completed returns 409 VIDEO_NOT_READY.

Permanently deletes a completed video and its stored file. Videos that are processing or failed cannot be deleted and return 409 VIDEO_NOT_DELETABLE.

{
  "data": { "id": "video_1759737600000_4f2a9c1e", "deleted": true },
  "error": null
}

A video costs credits in proportion to its length and resolution. The table shows the credits for a 5-second video; a 10-second video costs twice as much. Buy credits or a membership on the pricing page.

W3.0 edits cost the same as new videos of the requested length. A Seedance 2.5 edit is billed for its source video's length twice, as input and as output, at a lower rate: editing a 10-second source at 720P costs 38.78 credits. The creditCost of each video is the exact charge.

Uploads are checked against the rules of the model they are for. Files are not resized or converted, so prepare them before uploading.

• Up to 20 videos per account can render at the same time. More return 429 ACTIVE_GENERATION_LIMIT until one finishes.
• Prompts that need a full content safety review are limited to 30 a minute and 200 an hour per account. Beyond that, creating a video returns 429 PROMPT_MODERATION_RATE_LIMITED.
• A video still rendering after 3 hours fails with GENERATION_TIMED_OUT. Failed videos are always refunded.
• Upload URLs expire after 15 minutes, and uploaded files are deleted after 7 days.
• Videos made while your account holds a membership, or after it has bought credits, are stored permanently. Other videos stay with the video provider and may expire, so download them soon after they complete.
• Prompts can be up to 20,000 characters, with up to 10 images per video.