ToAPIs
    InicioToAPIs
    Generación de imágenesGPT Image 2.6, Gemini, FLUX…Generación de videoSeedance, Veo, Kling, Sora…Chat y redacciónGPT-5.6, Claude, DeepSeek…Voz y músicaLocuciones, TTS, audio
    NovedadSeedance 2.5
    PreciosDocumentación de APIMCP
    BlogAlternativas
    Iniciar sesiónEmpieza gratis
    Todos los modelosPreciosDocumentación de APIMCPBlogAlternativas
    Iniciar sesiónEmpieza gratis

    Idioma

    Esc
    • Seedance 2.5Generación de video
    • GPT Image 2Generación de imágenes
    • GPT Image 2.6Generación de imágenes
    • GPT Image 2.5Generación de imágenes
    • Veo 3.1 FastGeneración de video
    • Kling 3.0 TurboGeneración de video
    • Kling V4 FlashGeneración de video
    • Grok Video 1.5Generación de video
    • Nano Banana 2Generación de imágenes
    • Seedream 5.5Generación de imágenes
    • FLUXGeneración de imágenes
    • Sora 2Generación de video
    • Todos los modelos de imagenCategoría
    • Todos los modelos de videoCategoría
    • GPT-5.6 SolChat y código
    • Claude Opus 4.8Chat y código
    • Claude Opus 4.7Chat y código
    • DeepSeek V4 ProDeepSeek · Texto
    • Gemini Omni 1.1 FlashGoogle · Multimodal
    1. Inicio
    2. Blog
    3. Tutorial
    4. Alibaba Wan 3.0 Video API: Getting Started with Next-Gen Video Generation
    Volver a todos los artículos
    tutorial2026-11-208 min de lectura

    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 - Puntos clave
    • 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.

    Explora los modelos mencionados en este artículo

    UnknownVIDEO

    wan3.0-video

    Tarifa actual: 26.3 credits /second
    Guía del modeloProbar en la consolaObtener clave de API
    UnknownVIDEO

    wan3.0-video-prime

    Tarifa actual: 41.14 credits /second
    Guía del modeloProbar en la consolaObtener clave de API
    AlibabaVIDEO

    wan2.6

    Tarifa actual: 12 credits /second
    Guía del modeloProbar en la consolaObtener clave de API

    Artículos relacionados

    tutorial2026-11-18T10:00:00+08:008 min de lectura

    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:007 min de lectura

    Práctica con la API de Grok-Video-3: todo lo que necesitas saber sobre el motor de vídeo de xAI

    Guía práctica para llamar hoy a xAI Grok Video en ToAPIs: el catálogo público sigue listando grok-video-1.0 y grok-video-1.5, no grok-video-3, con el contrato actual de generaciones, los modos y la ruta de sondeo.

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

    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
    InicioToAPIs
    Pasarela empresarial de API de IA. Accede a GPT-5, Claude, Gemini y más de 200 modelos mediante una única API unificada.

    Modelos populares

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    Mostrar másMostrar menos
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • Todos los modelos

    Categorías de API

    • API de imagen con IA
    • API de vídeo con IA
    • API texto a vídeo
    • API imagen a vídeo
    Mostrar másMostrar menos
    • API de edición de imágenes con IA
    • API de LLM y razonamiento
    • Todas las herramientas API →

    Alternativas

    Alternativas
    • Alternativa a Kie.ai
    • Alternativa a Fal.ai
    • Alternativa a OpenRouter
    • Alternativa a Replicate
    • Alternativa a Wavespeed AI
    • Todas las comparativas →

    Guías destacadas

    Guías destacadas
    • Precios de Seedance 2.0 y 2.5
    • Guía de la API Seedance más económica
    • Guía de integración de MiniMax H3
    • Clave de API gratuita de Seedance 2
    • Inicio rápido de la API Seedance 2
    • Todos los artículos técnicos →

    Desarrolladores y plataforma

    Desarrolladores y plataforma
    • Documentación de API
    • MCP
    • Precios
    • Área de pruebas de modelos
    • LLMs.txt
    • Contactar con soporte
    • Directorio de guías de modelos
    Entidad operadora:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    Domicilio social:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    PrivacidadTérminosUso aceptableEliminación de datosConservación de datosSubencargados y regionesFacturación y reembolsosPolítica de cookiesMapa del sitioAcerca de

    © 2026 ToAPIs. Todos los derechos reservados.