ToAPIs
    HomeToAPIs
    Image GenerationGPT Image 2.6, Gemini, FLUX…Video GenerationSeedance, Veo, Kling, Sora…Chat & WritingGPT-5.6, Claude, DeepSeek…Speech & MusicVoiceover, TTS, Audio
    New ReleaseSeedance 2.5
    PricingAPI DocsMCP
    BlogAlternatives
    Log InStart Free
    All ModelsPricingAPI DocsMCPBlogAlternatives
    Log InStart Free

    Language

    Esc
    • Seedance 2.5Video Generation
    • GPT Image 2Image Generation
    • GPT Image 2.6Image Generation
    • GPT Image 2.5Image Generation
    • Veo 3.1 FastVideo Generation
    • Kling 3.0 TurboVideo Generation
    • Kling V4 FlashVideo Generation
    • Grok Video 1.5Video Generation
    • Nano Banana 2Image Generation
    • Seedream 5.5Image Generation
    • FLUXImage Generation
    • Sora 2Video Generation
    • All Image ModelsCategory
    • All Video ModelsCategory
    • GPT-5.6 SolChat & Coding
    • Claude Opus 4.8Chat & Coding
    • Claude Opus 4.7Chat & Coding
    • DeepSeek V4 ProDeepSeek · Text
    • Gemini Omni 1.1 FlashGoogle · Multimodal
    1. Home
    2. Blog
    3. Tutorial
    4. Alibaba Wan 3.0 Video API: Getting Started with Next-Gen Video Generation
    Back to all posts
    tutorial2026-11-208 min read

    Alibaba Wan 3.0 Video API: Getting Started with Next-Gen Video Generation

    A production quickstart for wan3.0-video and wan3.0-video-prime on ToAPIs: one All-in-One endpoint, first and last frames versus reference media, file or link references, video editing constraints, and the documented polling path.

    ToAPIs Engineering & Evaluation Team
    Wan 3.0Video APITutorialText-to-VideoAlibaba
    TL;DR - Key Takeaways
    • The documented public IDs are wan3.0-video (standard All-in-One) and wan3.0-video-prime. Planning drafts that use wan-3-prime are not the current contract. Both IDs share the same request schema on the Wan 3.0 generation reference; there is no separate Prime-only endpoint.
    • Submit jobs to POST /v1/videos/generations with a Bearer API key. Persist the task id and poll GET /v1/videos/generations/{id}. Ordinary tasks may also be queried with GET /v1/tasks/{id}. Official examples use https://toapis.com (mainland China: https://toapis.cn).
    • Duration is 2–30 seconds, or -1 for smart duration. Resolution is 480p, 720p, or 1080p (default 1080p). Use ratio or aspect_ratio, not both. First/last-frame mode cannot be mixed with reference images, videos, audio, files, or links.
    • Images, videos, audio, files, and pages must be public http(s) URLs. Do not send base64 or local paths. Video editing requires ratio=adaptive and duration=-1, with a 4–30 second source; violations fail with video_edit_parameters_required.
    • Do not reuse unverified draft dollar prices. A 2026-11-20 model-guide snapshot listed 26.3 credits / second for wan3.0-video and 41.14 credits / second for wan3.0-video-prime; confirm the live quote in your account catalog.

    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) lists wan3.0-video and wan3.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 poll GET /v1/videos/generations/{id} until completed or failed. Ordinary tasks may also be queried with GET /v1/tasks/{id}. Official examples use https://toapis.com (and https://toapis.cn for mainland China). Other guides in this series use https://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:// or https:// URLs only. Upload local files first and use the returned URL. Do not send base64 or local paths. At least one of prompt or media assets is required.
    • Unverified claims to drop: Draft unit prices such as $0.150 per 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 IDRole in this guideDocumented jobs
    wan3.0-videoDefault / standard All-in-One IDText-to-video, first/last frames, multimodal references, file or link, edit and extend
    wan3.0-video-primeSister Prime ID on the same schemaSame request structure as wan3.0-video; choose it only when your catalog lists it and you intend the Prime SKU
    wan2.6Related earlier Wan ID; see the Wan 2.6 generation referenceText-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):

    FieldDocumented valuesNotes
    promptStringContent, 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
    durationIntegers 2–30, or -1Default 5. -1 is smart duration — the model chooses the length
    ratioadaptive (default), 16:9, 9:16, 1:1, 4:3, 3:4aspect_ratio is a compatible alias; do not pass both
    resolution480p, 720p, 1080p (default 1080p)All three are documented on this contract
    audioBoolean, default trueAudio on by default
    watermarkBoolean, default falseOff by default
    prompt_extendBoolean, default trueAn LLM rewrite can improve short prompts and adds latency; set false to use the prompt verbatim
    seedOptional integerSame parameters plus seed help reproduce similar results
    image_with_roles{url, role} arrayrole is first_frame or last_frame. At most one of each; last_frame requires first_frame
    reference_imagesUp to 10 public image URLsCannot be mixed with first/last frames
    video_listUp to 5 clips, total duration ≤15sEach item is {"video_url": "..."}
    audio_with_rolesUp to 5 clips, total ≤15sEach item is {url, role: "reference_audio"}
    metadata.mediaOne file or one link{type, url}. File and link cannot be combined, and cannot be mixed with first/last-frame mode
    disable_nsfwBoolean, default trueToAPIs 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 contentSupported?Notes
    Prompt onlyYesText-to-video
    First frame onlyYesFirst-frame control
    First and last frameYesLast frame cannot be used alone
    Reference images and reference videosYesCan be combined, including with reference audio
    First frame and reference videoNoFirst/last-frame mode and reference-asset mode are mutually exclusive
    File and web linkNoMutually 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).

    Empty multimodal panels merging through a hexagonal gateway into one output frame

    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

    bash
    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:

    bash
    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.

    python
    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 stateCommon categoryRecommended action
    400Invalid field, mixed first/last frames with reference assets, both ratio and aspect_ratio, or a file plus a linkConfirm wan3.0-video or wan3.0-video-prime, drop one exclusive family, and use public URLs only
    401Missing or invalid API keyRotate the key in the ToAPIs dashboard and confirm the Authorization: Bearer header
    429Rate or concurrency limitHonor Retry-After when present; back off with jitter; retry only when safe
    5xx or client timeoutTemporary gateway or upstream issueQuery the existing task id before resubmitting
    status: queued or in_progressNot an errorWait and poll again; prompt_extend can add latency
    status: failed with video_edit_parameters_requiredEdit constraints were not metSet ratio to adaptive, duration to -1, and use a 4–30 second source
    status: failed (other)Generation did not succeedRead error.code and error.message (and error.reason when present). Do not retry an unchanged policy-rejected payload

    WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)WaitTime=min(MaxWait,BaseInterval×2attempt)+Uniform(0,1)


    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.

    Estimated cost=successful billable seconds×current account rate for that model and resolution\text{Estimated cost} = \text{successful billable seconds} \times \text{current account rate for that model and resolution}Estimated cost=successful billable seconds×current account rate for that model and resolution

    • Start on wan3.0-video in 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) and prompt_extend change 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=video and 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 (and wan3.0-video-prime, if you need it) appears for your key via GET /v1/models?type=video — do not send wan-3-prime.
    • Smoke-test the cURL snippet with duration: 5, ratio: "16:9", and resolution: "1080p".
    • Poll GET /v1/videos/generations/{id} with a bounded deadline, and download the result before expires_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.

    Explore Models Mentioned in This Post

    UnknownVIDEO

    wan3.0-video

    Current Rate: 26.3 credits /second
    Model GuideTry in ConsoleGet API Key
    UnknownVIDEO

    wan3.0-video-prime

    Current Rate: 41.14 credits /second
    Model GuideTry in ConsoleGet API Key
    AlibabaVIDEO

    wan2.6

    Current Rate: 12 credits /second
    Model GuideTry in ConsoleGet API Key

    Related Articles

    tutorial2026-11-18T10:00:00+08:008 min read

    Kling 3.0 Omni API Deep Dive: Multi-Shot Video Generation and Physics Coherence

    A hands-on guide to kling-v3-omni on ToAPIs: official Omni placeholders, image_list, video_list, and element_list, first and end frames, and the documented polling path — without an undocumented shots array.

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Omni
    tutorial2026-11-17T10:00:00+08:006 min read

    Hands-on with Grok-Video-3 API: Everything You Need to Know About xAI's Video Engine

    A hands-on guide to calling xAI Grok Video on ToAPIs today: the public catalog still lists grok-video-1.0 and grok-video-1.5, not grok-video-3, with the current generations contract, modes, and polling path.

    TO
    ToAPIs Engineering & Evaluation Team
    #Grok Video
    comparison2026-11-20T10:00:00+08:008 min read

    Wan 3.0 Prime vs Wan 2.6 Flash: Generation Speed, Frame Fidelity, and Cost

    A contract-faithful comparison of wan3.0-video-prime and wan2.6-flash on ToAPIs: documented modes, duration and resolution windows, official pricing snapshots, and why published pages do not support numeric latency or savings claims.

    TO
    ToAPIs Engineering & Evaluation Team
    #Wan 3.0 Prime
    ToAPIs
    HomeToAPIs
    Enterprise AI API Gateway. Access GPT-5, Claude, Gemini and 200+ models through one unified API.

    Popular Models

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    Show moreShow less
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • All models

    API Categories

    • AI Image API
    • AI Video API
    • Text-to-Video API
    • Image-to-Video API
    Show moreShow less
    • AI Image Editing API
    • LLM & Reasoning API
    • All API tools →

    Alternatives

    Alternatives
    • Kie.ai alternative
    • Fal.ai alternative
    • OpenRouter alternative
    • Replicate alternative
    • Wavespeed AI alternative
    • All comparisons →

    Featured Guides

    Featured Guides
    • Seedance 2.0 vs 2.5 pricing
    • Cheapest Seedance API guide
    • MiniMax H3 integration guide
    • Free Seedance 2 API key
    • Seedance 2 API quickstart
    • All engineering posts →

    Developers & Platform

    Developers & Platform
    • API documentation
    • MCP
    • Pricing
    • Model playground
    • LLMs.txt
    • Contact support
    • Model guide directory
    Operating entity:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    Registered office:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    PrivacyTermsAcceptable UseData DeletionData RetentionSubprocessors & RegionsBilling & RefundsCookie PolicySitemapAbout

    © 2026 ToAPIs. All rights reserved.