Wan 3.0

Generate 2–30 second videos at 720p or 1080p from text, from one or more images, or from reference videos and audio.

• Asynchronous: the create call returns a task ID; the video arrives when the task succeeds.
• Clips of 2 to 30 seconds in one request; duration is a whole number of seconds.
• Four ways in: text only, one image, several images (up to 10), or reference videos and audio (up to 5 of each). Images and references cannot be mixed.
• Billed by the resolution and the number of seconds you request. A failed task costs nothing.

Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.

Model IDs

Two Wan 3.0 models share this endpoint and accept exactly the same request. The values below come straight from the gateway contract.

Endpoint and authentication

POST https://api.beatapi.io/v1/videos/tasks

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

How a request works

Input modes

Request parameters

The gateway also checks these combinations before creating the task:

• images cannot be combined with reference inputs

Input media limits

The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.

• The gateway does not read your image, video or audio files when it creates the task, so no size, resolution, length or format limit is checked for this model; only the field rules above apply.
• A link the model cannot fetch or use fails the task after it was created, usually with bad_request (or content_policy_violation when moderation refuses an input), and the task is refunded in full.
• Have a local file? Upload it with POST /v1/files (png, jpg, jpeg, webp, mp3, wav, aac, m4a, mp4 or mov; up to 50 MB, 100 MB for video) and pass the returned data.url.

Which inputs go together

Fields this model does not accept

Sending one of these is refused before anything is charged, instead of being ignored:

• reference_images, generate_audio, seed, quality, sound, task_type, output_format, watermark and the other fields of other video models → field "seed" is not supported by model wan-3.0 (with the field you sent). Put pictures in images.
• Any field the video endpoint does not know at all → unknown field: <name>.

Request examples

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan-3.0",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, steam rising from food stalls",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Text to video

A 5-second 720p landscape clip.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan-3.0",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, steam rising from food stalls",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Image to video

A 10-second 1080p square clip made from one image.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan-3.0",
  "prompt": "The camera orbits the bottle as soft light sweeps across its surface",
  "images": [
    "https://media.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 10,
  "aspect_ratio": "1:1",
  "resolution": "1080p"
}'

Several images

Two images, passed to the model in list order.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan-3.0",
  "prompt": "The camera pushes in from the bottle on the table to the singer on a neon stage in one continuous move",
  "images": [
    "https://media.beatapi.io/samples/smart-bottle.png",
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 8,
  "resolution": "720p"
}'

Reference video and audio

Replace the video link with your own public MP4. A 30-second portrait clip in the style of the reference.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan-3.0",
  "prompt": "A dancer moves in the style of the reference video, in time with the reference music, warm spotlights",
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "reference_audios": [
    "https://media.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 30,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "wan-3.0",
    "capability_version": 1,
    "media_type": "video",
    "model": "wan-3.0",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.63,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.63,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "wan-3.0",
    "capability_version": 1,
    "media_type": "video",
    "model": "wan-3.0",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.63,
      "credits_settled": 0.63,
      "credits_refunded": 0,
      "credits_charged": 0.63,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Output fields

Failed task

A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "wan-3.0",
    "capability_version": 1,
    "media_type": "video",
    "model": "wan-3.0",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.63,
      "credits_settled": 0,
      "credits_refunded": 0.63,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Complete example

Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "wan-3.0",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, steam rising from food stalls",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Billing

• The price follows the resolution and the number of seconds you request (duration, 5 if you leave it out). 1080p costs more per second than 720p. aspect_ratio does not change it.
• The table below shows 8-second clips; other lengths are priced per second at the same rate for their resolution.
• The price is reserved when the task is created; data.usage.billable_duration_seconds shows the seconds it is based on.
• A failed task, including one refused by moderation after submission, is refunded in full.

Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.

Common errors

HTTP errors at a glance

Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}