Wan 3.0 Prime API

What it does

Wan 3.0 Prime makes a video of 2 to 30 seconds, with a soundtrack by default, from a prompt and optional media: image frames, reference images, videos and audio, a document or a web page. It takes the same input as Wan 3.0, at 720P only. The prompt goes in input.prompt, the media in input.media (each item is {"type", "url"}), and the settings in input.parameters, where duration is required. The media you send choose the mode:

Every example below is a complete body for POST /v1/generations. Send the same body to POST /v1/estimates first: it is free, creates no task, holds no Credits, and refuses an invalid body with the same 422 as a create. The https://media.vizoapi.com/... files are public samples, so the examples run as they are; replace https://example.com/... with your own file or an uploaded ast_... asset ID (a file or link takes a URL only).

Modes

Text to video

Only prompt, up to 20,000 characters. Set parameters.ratio to 16:9, 4:3, 1:1, 3:4 or 9:16; adaptive is the default. parameters.duration is 2 to 30 seconds, or -1 to let the model choose.

{
  "model": "wan-3-0-prime",
  "input": {
    "prompt": "A paper boat drifts across a still pond at dawn, mist on the water, slow push-in, soft natural light",
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5,
      "audio": true
    }
  }
}

First frame

The video starts on your image. Send one first_frame and keep ratio at adaptive so the output takes the image's shape. The prompt describes what happens next; it may be left out.

{
  "model": "wan-3-0-prime",
  "input": {
    "prompt": "The hominids step back as the sun rises behind the monolith, slow push-in",
    "media": [
      { "type": "first_frame", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg" }
    ],
    "parameters": {
      "resolution": "720P",
      "duration": 5
    }
  }
}

First and last frame

The video moves from the first image to the last. Send at most one first_frame and one last_frame (rule frame_repeated). Frames cannot be combined with any reference item, file or link (rule frames_with_references).

{
  "model": "wan-3-0-prime",
  "input": {
    "prompt": "The ring-shaped station slowly turns to face the camera as an amber planet rises behind it",
    "media": [
      { "type": "first_frame", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" },
      { "type": "last_frame", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/ending.jpg" }
    ],
    "parameters": {
      "resolution": "720P",
      "duration": 6
    }
  }
}

Reference images and video

Reference images give the model characters, objects, places or a style; reference videos give it motion, camera movement or a subject to reuse. Send up to 10 images and 5 videos (rules too_many_reference_images, too_many_reference_videos); the videos run at most 15 seconds together, and input plus output at most 30 seconds. Name each item in the prompt by kind and order: "image 1", "video 1". Any reference_video moves the task to the -video tier of its resolution, which bills the input video's seconds too (see [How it is billed](#how-it-is-billed)).

{
  "model": "wan-3-0-prime",
  "input": {
    "prompt": "Follow the camera movement of video 1, set on the space station from image 1, then cut to the black monolith from image 2",
    "media": [
      { "type": "reference_image", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/station.jpg" },
      { "type": "reference_image", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/keyframes/monolith.jpg" },
      { "type": "reference_video", "url": "https://media.vizoapi.com/samples/seedance-2-5/odyssey-v1/1.mp4" }
    ],
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5
    }
  }
}

Reference audio

Reference audio gives the model a voice, rhythm or sound to follow. Send up to 5 items (rule too_many_reference_audios), at most 15 seconds together. Audio can be mixed with reference images and videos, and never changes the tier.

{
  "model": "wan-3-0-prime",
  "input": {
    "prompt": "The astronaut from image 1 speaks to the camera inside the station, in the voice of audio 1",
    "media": [
      { "type": "reference_image", "url": "https://example.com/astronaut.png" },
      { "type": "reference_audio", "url": "https://example.com/voice.mp3" }
    ],
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 8
    }
  }
}

Document or web page

A file (a document such as a slide deck) or a link (a public web page that needs no login) gives the model material to turn into a video, such as a product ad from its brochure. Send at most one of them, never both (rules too_many_files, too_many_links, file_with_link). Both take a public https URL only, not an asset ID, and the model fetches them itself, so their size and format are checked only when the task runs. They can be combined with reference items, but not with frames.

{
  "model": "wan-3-0-prime",
  "input": {
    "prompt": "A minimal, futuristic 15-second product ad for the smart glasses on this page",
    "media": [
      { "type": "link", "url": "https://example.com/product-page" }
    ],
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 15
    }
  }
}

Input limits

A media value is a public https URL (up to 4,000 characters) or, for images, videos and audio, an ast_... asset ID from your project. Plain http, private or local addresses, URLs with a user name or #fragment, and Base64 data are refused with 422 (rule bad_format). The model fetches a linked file itself, possibly some time after acceptance, so keep it reachable until the task closes; if it cannot, the task fails with input_media_unreachable. See Model inputs and media.

Output

A succeeded task lists one MP4 in result.outputs: take its asset_id and get a download URL with download an asset. Outputs are kept for 7 days. See Get results.

How it is billed

The input selects the tier: 720p, or 720p-video when media has any reference_video. Images, audio, file and link never change the tier or the price, and neither do ratio, audio, seed or watermark.

Input seconds are the length of all reference videos together, rounded up, at most 15. When a video's length cannot be read at create, or the request also has a file or link, the hold counts 15 input seconds. With duration: -1 the hold counts 30 output seconds; when every reference video is measured, it counts only what fits in 30 seconds with the input, and the billed seconds stop at 30. The sample video in the examples runs 12.06 seconds, so it holds 13 input seconds.

Holds:

The hold is only the estimate. A succeeded task is charged for the output seconds the model reports, plus its reported input seconds on a -video tier, to the millisecond, at the tier's rate. So price.charged can be below the hold (the rest is released) or above it, with no cap. Usage above the hold comes from your available balance; what it cannot cover is owed, and new creates get 402 balance_negative until a top-up. A failed or unresolved task is not charged. Send the body to POST /v1/estimates to see the exact hold and its basis (output_seconds, input_seconds, billed_seconds, auto). See Billing.

Errors and behaviors

Moderation is always on; no field turns it off. Each task has a deadline of 24 hours from acceptance. A task still unfinished then closes as unresolved, releases its hold and is not charged; if its result arrives later, it is added at no charge and late_result_available becomes true. See Errors and Get results.

Prompting tips

• Name media by kind and order in media: "image 1", "image 2", "video 1", "audio 1". Say what to take from each: "the character from image 1", "the camera movement of video 1", "the voice of audio 1".
• Write the shot, not just the subject: subject, action, setting, camera movement, light and style. For several shots, number them ("Shot 1: …, Shot 2: …").
• Describe the sound you want when audio is on: ambience, effects, music, or a spoken line in quotes.
• With first and last frames, describe the motion between them; the frames already fix the start and end.
• With a file or link, say what kind of video to make from it (an ad, an explainer) and its tone; the model picks the content from the material.
• Keep a reference video short when you want a long output: input and output share 30 seconds.
• Need 480P or 1080P, or a lower price per second? Send the same body to Wan 3.0: only model and resolution change.

价格

输入决定价格档位。视频按输出秒数计费；含输入视频的档位同时计入输入秒数。

规则

• Send a prompt, media or both.
• first_frame and last_frame (at most one each) cannot be combined with reference items, file or link.
• Reference videos total at most 15 seconds, reference audios at most 15 seconds, and reference video input plus output length at most 30 seconds.

输入字段

在 input 中发送这些字段。表中没有的字段会被拒绝，返回 HTTP 422 invalid_input。

示例

完整的创建请求、202 响应，以及任务成功后的状态。

请求

curl https://api.vizoapi.com/v1/generations \
  -H "Authorization: Bearer $VIZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan-3-0-prime",
  "input": {
    "prompt": "A paper boat drifting on a pond at dawn, slow dolly in",
    "parameters": {
      "ratio": "16:9",
      "duration": 5
    }
  },
  "metadata": {
    "client_reference": "my-unique-reference-1"
  }
}'

import os, requests

# Send once: do not retry this request automatically.
task = requests.post(
    "https://api.vizoapi.com/v1/generations",
    headers={"Authorization": f"Bearer {os.environ['VIZO_API_KEY']}"},
    json={
      "model": "wan-3-0-prime",
      "input": {
        "prompt": "A paper boat drifting on a pond at dawn, slow dolly in",
        "parameters": {
          "ratio": "16:9",
          "duration": 5
        }
      },
      "metadata": {
        "client_reference": "my-unique-reference-1"
      }
    },
    timeout=60,
).json()
print(task["id"], task["status"])

// Send once: do not retry this request automatically.
const res = await fetch("https://api.vizoapi.com/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIZO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "wan-3-0-prime",
    "input": {
      "prompt": "A paper boat drifting on a pond at dawn, slow dolly in",
      "parameters": {
        "ratio": "16:9",
        "duration": 5
      }
    },
    "metadata": {
      "client_reference": "my-unique-reference-1"
    }
  }),
});
const task = await res.json();
console.log(task.id, task.status);

响应

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "wan-3-0-prime",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "processing",
  "execution_status": "processing",
  "delivery_status": "pending",
  "billing_status": "pending",
  "version": 1,
  "price": {
    "unit": "credit",
    "estimated": "140.000",
    "reserved": "0.000",
    "charged": "0.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": null,
  "error": null,
  "result": null
}

{
  "id": "gen_01JD8Z5QW3XR",
  "model": "wan-3-0-prime",
  "source": "api",
  "created_at": "2026-11-08T09:00:00Z",
  "customer_resolution_deadline": "2026-11-09T09:00:00Z",
  "late_result_available": false,
  "metadata": {
    "client_reference": "my-unique-reference-1"
  },
  "status": "succeeded",
  "execution_status": "succeeded",
  "delivery_status": "ready",
  "billing_status": "settled",
  "version": 4,
  "price": {
    "unit": "credit",
    "estimated": "140.000",
    "reserved": "0.000",
    "charged": "140.000",
    "refunded": "0.000"
  },
  "allowed_actions": [],
  "closed_at": "2026-11-08T09:01:31Z",
  "error": null,
  "result": {
    "asset_id": "ast_01JD8Z9M2C4V",
    "outputs": [
      {
        "index": 0,
        "asset_id": "ast_01JD8Z9M2C4V",
        "content_type": "video/mp4"
      }
    ]
  }
}