Alibaba Wan 3.0 Video API: Getting Started with Next-Gen Video Generation
Target Model:
wan3.0-video(optional sister ID:wan3.0-video-prime)
Inference Endpoint:https://api.toapis.com/v1/videos/generations
Related: Wan 3.0 Prime vs Wan 2.6 Flash · Kling Video O1 long-form continuity · Wan 3.0 reference · wan3.0-video model guide · wan3.0-video-prime model guide
1. TL;DR & Performance Overview
- Catalog first: Planning drafts sometimes write
wan-3-prime. That string is not a documented public ID. A 2026-11-20 check of the official Wan 3.0 generation reference (HTTP 200) listswan3.0-videoandwan3.0-video-prime. Both models use the same All-in-One API on that page. There was no separate Prime-only docs path. - Contract: Submit asynchronously to
POST /v1/videos/generations, then pollGET /v1/videos/generations/{id}untilcompletedorfailed. Ordinary tasks may also be queried withGET /v1/tasks/{id}. Official examples usehttps://toapis.com(andhttps://toapis.cnfor mainland China). Other guides in this series usehttps://api.toapis.com. Pick one origin and keep it consistent. - Modes on one schema: Text-to-video; first-frame or first/last-frame control; joint generation with reference images, videos, and audio; a single file or public web page; and video editing or extension from a reference clip. First/last-frame mode and reference-asset mode are mutually exclusive.
- Media: Send public
http://orhttps://URLs only. Upload local files first and use the returned URL. Do not send base64 or local paths. At least one ofpromptor media assets is required. - Unverified claims to drop: Draft unit prices such as
$0.150per 5 seconds are not current ToAPIs documentation. Confirm live rates and channel support in your account.
2. Official Wan 3.0 IDs, Parameters, and Combination Rules
Use one of the two public model names in the model field. Do not substitute a draft alias or invent a Prime mode flag.
| Catalog ID | Role in this guide | Documented jobs |
|---|---|---|
wan3.0-video | Default / standard All-in-One ID | Text-to-video, first/last frames, multimodal references, file or link, edit and extend |
wan3.0-video-prime | Sister Prime ID on the same schema | Same request structure as wan3.0-video; choose it only when your catalog lists it and you intend the Prime SKU |
wan2.6 | Related earlier Wan ID; see the Wan 2.6 generation reference | Text-to-video, image-to-video, and reference video on a different parameter map (no 480p; duration 5/10/15) |
Core request fields (shared by both Wan 3.0 IDs):
| Field | Documented values | Notes |
|---|---|---|
prompt | String | Content, motion, camera, and sound. At least one of prompt or media assets is required. Refer to assets as “image 1”, “video 1”, “audio 1” in array order |
duration | Integers 2–30, or -1 | Default 5. -1 is smart duration — the model chooses the length |
ratio | adaptive (default), 16:9, 9:16, 1:1, 4:3, 3:4 | aspect_ratio is a compatible alias; do not pass both |
resolution | 480p, 720p, 1080p (default 1080p) | All three are documented on this contract |
audio | Boolean, default true | Audio on by default |
watermark | Boolean, default false | Off by default |
prompt_extend | Boolean, default true | An LLM rewrite can improve short prompts and adds latency; set false to use the prompt verbatim |
seed | Optional integer | Same parameters plus seed help reproduce similar results |
image_with_roles | {url, role} array | role is first_frame or last_frame. At most one of each; last_frame requires first_frame |
reference_images | Up to 10 public image URLs | Cannot be mixed with first/last frames |
video_list | Up to 5 clips, total duration ≤15s | Each item is {"video_url": "..."} |
audio_with_roles | Up to 5 clips, total ≤15s | Each item is {url, role: "reference_audio"} |
metadata.media | One file or one link | {type, url}. File and link cannot be combined, and cannot be mixed with first/last-frame mode |
disable_nsfw | Boolean, default true | ToAPIs platform parameter, not forwarded upstream. Only an explicit JSON false enables fallback when the account and sales region are eligible; mainland China stays disabled |
Asset combination rules from the official table:
| Request content | Supported? | Notes |
|---|---|---|
| Prompt only | Yes | Text-to-video |
| First frame only | Yes | First-frame control |
| First and last frame | Yes | Last frame cannot be used alone |
| Reference images and reference videos | Yes | Can be combined, including with reference audio |
| First frame and reference video | No | First/last-frame mode and reference-asset mode are mutually exclusive |
| File and web link | No | Mutually exclusive |
If the API returns a message such as “Wan 3.0 cannot mix first/last frames with reference assets/files/web pages in the same request,” drop one of the two families and resubmit.
Video editing is a prompt-classified path, not a separate endpoint: include editing intent (for example “edit the video”, “remove”, “replace”) and pass a reference clip. Those jobs require ratio to be adaptive and duration to be -1, and the input must be 4–30 seconds long. Extension uses wording such as “extend” or “continue”, with duration set to -1 or to the source length plus the extension (total ≤ 30 seconds).

Figure 1: A documented Wan 3.0 payload is submitted to POST /v1/videos/generations; poll the same task id and read result.data[0].url only after status is completed.
For a capability and cost comparison against Wan 2.6 Flash, see Wan 3.0 Prime vs Wan 2.6 Flash. For long-form continuity on a different family with a 3–10 second window, see the Kling Video O1 guide.
3. Production Implementation: cURL & Python
International examples in this series use https://api.toapis.com. Official docs tell mainland China users to use https://toapis.cn. Keep one origin per environment.
Step 1: cURL dispatch for text-to-video
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "An orange cat running through the streets of Tokyo after rain, cinematic camera work",
"duration": 5,
"ratio": "16:9",
"resolution": "1080p",
"audio": true,
"watermark": false
}'
A first-and-last-frame request uses image_with_roles and must not include reference media, files, or links:
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "The camera pushes in naturally as the person transitions from standing to smiling and waving",
"duration": 8,
"ratio": "adaptive",
"resolution": "1080p",
"image_with_roles": [
{"url": "https://example.com/first-frame.png", "role": "first_frame"},
{"url": "https://example.com/last-frame.png", "role": "last_frame"}
]
}'
Step 2: Python helper and poller
The snippet follows the documented task-status path and the queued / in_progress / completed / failed statuses. Confirm id, result.data[0].url, and the envelope against the API reference for your account before you ship.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_IDS = {"wan3.0-video", "wan3.0-video-prime"}
RATIOS = {"adaptive", "16:9", "9:16", "1:1", "4:3", "3:4"}
RESOLUTIONS = {"480p", "720p", "1080p"}
def dispatch_wan30(
prompt: str | None = None,
*,
model: str = "wan3.0-video",
duration: int = 5,
ratio: str = "16:9",
resolution: str = "1080p",
audio: bool = True,
watermark: bool = False,
prompt_extend: bool | None = None,
image_with_roles: list[dict] | None = None,
reference_images: list[str] | None = None,
video_list: list[dict] | None = None,
audio_with_roles: list[dict] | None = None,
media: list[dict] | None = None,
) -> str:
if model not in DOCUMENTED_IDS:
raise ValueError("Send wan3.0-video or wan3.0-video-prime; wan-3-prime is not a documented public ID")
if duration != -1 and duration not in range(2, 31):
raise ValueError("duration must be 2–30 or -1")
if ratio not in RATIOS:
raise ValueError("unsupported ratio")
if resolution not in RESOLUTIONS:
raise ValueError("resolution must be 480p, 720p, or 1080p")
roles = [item.get("role") for item in (image_with_roles or [])]
if "last_frame" in roles and "first_frame" not in roles:
raise ValueError("last_frame requires first_frame")
has_frames = bool(image_with_roles)
has_refs = any([reference_images, video_list, audio_with_roles, media])
if has_frames and has_refs:
raise ValueError("first/last-frame mode cannot mix with reference assets, files, or links")
if media and len(media) > 1:
raise ValueError("a single request accepts at most one file or one web page")
if media and len({item.get("type") for item in media}) > 1:
raise ValueError("file and link cannot be used together")
if not prompt and not has_frames and not has_refs:
raise ValueError("provide a prompt or at least one media asset")
if reference_images and len(reference_images) > 10:
raise ValueError("reference_images is documented as at most 10")
if video_list and len(video_list) > 5:
raise ValueError("video_list is documented as at most 5 clips")
if audio_with_roles and len(audio_with_roles) > 5:
raise ValueError("audio_with_roles is documented as at most 5 clips")
payload: dict = {
"model": model,
"duration": duration,
"ratio": ratio,
"resolution": resolution,
"audio": audio,
"watermark": watermark,
}
if prompt:
payload["prompt"] = prompt
if prompt_extend is not None:
payload["prompt_extend"] = prompt_extend
if image_with_roles:
payload["image_with_roles"] = image_with_roles
if reference_images:
payload["reference_images"] = reference_images
if video_list:
payload["video_list"] = video_list
if audio_with_roles:
payload["audio_with_roles"] = audio_with_roles
if media:
payload["metadata"] = {"media": media}
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 900) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_wan30(
"An orange cat running through the streets of Tokyo after rain, cinematic camera work",
duration=5,
ratio="16:9",
resolution="1080p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Store the prompt template version next to the task record so you can tell a parameter change from a wording change. Download the file before expires_at; the status reference documents a 30-day retention window. If you enable prompt_extend (the default), expect additional latency on short prompts — the official page states this qualitatively and does not publish a measured delay.
4. Error Handling & Status Matrix
The categories below are diagnostic starting points, not a guarantee of exact ToAPIs error codes. A successful HTTP query still requires you to read task status. See the error reference for request errors versus status: failed reasons such as content_policy_rejected, insufficient_user_balance, generation_timeout, or video_edit_parameters_required.
| HTTP or task state | Common category | Recommended action |
|---|---|---|
400 | Invalid field, mixed first/last frames with reference assets, both ratio and aspect_ratio, or a file plus a link | Confirm wan3.0-video or wan3.0-video-prime, drop one exclusive family, and use public URLs only |
401 | Missing or invalid API key | Rotate the key in the ToAPIs dashboard and confirm the Authorization: Bearer header |
429 | Rate or concurrency limit | Honor Retry-After when present; back off with jitter; retry only when safe |
5xx or client timeout | Temporary gateway or upstream issue | Query the existing task id before resubmitting |
status: queued or in_progress | Not an error | Wait and poll again; prompt_extend can add latency |
status: failed with video_edit_parameters_required | Edit constraints were not met | Set ratio to adaptive, duration to -1, and use a 4–30 second source |
status: failed (other) | Generation did not succeed | Read error.code and error.message (and error.reason when present). Do not retry an unchanged policy-rejected payload |
5. Pricing & FinOps ROI
The Wan 3.0 generation reference does not publish a dollar or credit table. A 2026-11-20 fetch of the model-guide pages showed a pricing reference of 26.3 credits / second for wan3.0-video and 41.14 credits / second for wan3.0-video-prime, and both pages stated that final billing follows the current account quote and current duration and resolution rules. Treat those credit figures as a snapshot, not a contract for every resolution or mode. Do not convert credits to currency yourself, and do not reuse planning-draft dollar rates.
- Start on
wan3.0-videoin a mid-range duration such as 5 seconds, and raise resolution or switch to Prime only after the prompt and asset combination are stable. - Smart duration (
-1) andprompt_extendchange the work the model does. They are documented capabilities, not a reason to assume a fixed per-job price or latency. - A display price is not a channel guarantee. Confirm the ID and the live quote with
GET /v1/models?type=videoand your account catalog before you forecast a batch.
6. Frequently Asked Questions
See the FAQ block in frontmatter. Summary: send wan3.0-video or wan3.0-video-prime, not wan-3-prime; first/last frames cannot mix with reference assets; duration is 2–30 seconds or -1; editing needs ratio=adaptive and duration=-1; always poll the generations status path and persist the task id.
7. Action Checklist
- Create a key on the ToAPIs Developer Portal.
- Confirm
wan3.0-video(andwan3.0-video-prime, if you need it) appears for your key viaGET /v1/models?type=video— do not sendwan-3-prime. - Smoke-test the cURL snippet with
duration: 5,ratio: "16:9", andresolution: "1080p". - Poll
GET /v1/videos/generations/{id}with a bounded deadline, and download the result beforeexpires_at. - Next: Wan 3.0 Prime vs Wan 2.6 Flash for a documented capability and cost comparison, and the wan3.0-video model guide for the live catalog status.







