ToAPIs
    InícioToAPIs
    Geração de imagensGPT Image 2.6, Gemini, FLUX…Geração de vídeoSeedance, Veo, Kling, Sora…Chat e escritaGPT-5.6, Claude, DeepSeek…Voz e músicaLocuções, TTS, áudio
    NovidadeSeedance 2.5
    PreçosDocumentação da APIMCP
    BlogAlternativas
    EntrarComece grátis
    Todos os modelosPreçosDocumentação da APIMCPBlogAlternativas
    EntrarComece grátis

    Idioma

    Esc
    • Seedance 2.5Geração de vídeo
    • GPT Image 2Geração de imagens
    • GPT Image 2.6Geração de imagens
    • GPT Image 2.5Geração de imagens
    • Veo 3.1 FastGeração de vídeo
    • Kling 3.0 TurboGeração de vídeo
    • Kling V4 FlashGeração de vídeo
    • Grok Video 1.5Geração de vídeo
    • Nano Banana 2Geração de imagens
    • Seedream 5.5Geração de imagens
    • FLUXGeração de imagens
    • Sora 2Geração de vídeo
    • Todos os modelos de imagemCategoria
    • Todos os modelos de vídeoCategoria
    • GPT-5.6 SolChat e código
    • Claude Opus 4.8Chat e código
    • Claude Opus 4.7Chat e código
    • DeepSeek V4 ProDeepSeek · Texto
    • Gemini Omni 1.1 FlashGoogle · Multimodal
    1. Início
    2. Blog
    3. Tutorial
    4. Kling 3.0 Omni API Deep Dive: Multi-Shot Video Generation and Physics Coherence
    Voltar a todos os artigos
    tutorial2026-11-188 min de leitura

    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.

    ToAPIs Engineering & Evaluation Team
    Kling OmniVideo APIMulti-ShotText-to-VideoTutorial
    TL;DR - Principais conclusões
    • The documented public model ID is kling-v3-omni. Planning drafts that use kling-3-omni are not the current API contract; send the documented string only.
    • 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}. Do not invent a /v1/videos/tasks path or a query-string video-status URL.
    • There is no documented shots array. Teach multi-shot continuity with official placeholders <<<image_N>>>, <<<video_N>>>, and <<<element_N>>>, plus metadata.image_list, metadata.element_list, and video_list.
    • Images and reference videos must be public http(s) URLs. Upload local files with POST /v1/uploads/images first; base64 is not accepted. audio and video_list are mutually exclusive.
    • Do not reuse unverified per-second dollar prices or SLA figures from planning drafts. The Omni billing map uses std/pro plus base, Sound, or Video SKUs; confirm the live rate in your account catalog.

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

    Target Model: kling-v3-omni
    Inference Endpoint: https://api.toapis.com/v1/videos/generations
    Related: Kling 3.0 Turbo automation guide · Kling V4 Flash API guide · kling-v3-omni reference · kling-v3-omni model guide


    1. TL;DR & Performance Overview

    • Catalog first: Planning drafts sometimes write kling-3-omni. That string is not the documented public ID. A 2026-11-18 check of the official generation reference and the model-guide page (HTTP 200) lists kling-v3-omni as the fixed model value. Send that exact string.
    • 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.
    • No shots[] field: Multi-shot continuity and physics coherence are prompt-plus-reference problems. Use official placeholders <<<image_N>>>, <<<video_N>>>, and <<<element_N>>> with metadata.image_list, video_list, and metadata.element_list. List order must match placeholder order; the system will not auto-insert placeholders or auto-add a first frame.
    • Media: Send public http:// or https:// URLs only. Upload local files with POST /v1/uploads/images and use the returned URL. Do not send base64. audio and video_list are mutually exclusive.
    • Unverified claims to drop: Draft unit prices such as $0.022/s, SLA figures such as 99.95%, or a custom shots schema are not current ToAPIs documentation. Confirm live rates and channel support in your account.

    2. Official Omni ID, Placeholders, and Coherence Workflows

    Use the public model name in the model field. Do not substitute a draft alias, a URL slug, or a related but different catalog ID.

    Catalog IDRole in this guideDocumented jobs
    kling-v3-omniHero ID for this articleText-to-video plus official Omni references: image_list, video_list, and element_list
    kling-3.0-turboSister short-form ID; see the Turbo guideText-to-video and first-frame image-to-video only — not an Omni reference contract
    kling-v3Related non-Omni v3 IDA separate generation reference — do not reuse Omni lists here unless its own docs say so

    Core request fields on kling-v3-omni:

    FieldDocumented valuesNotes
    promptRequired stringReference assets with 1-based placeholders
    modestd (default) or prostd maps to 720P; pro maps to 1080P, and the same flag drives billing resolution
    durationIntegers 3–15 (default 5)Not limited to 5 or 10 seconds
    aspect_ratioCommon values 16:9 (default), 9:16, 1:1Prefer the generation reference if a marketing parameter table is shorter
    audioBoolean, default falsetrue bills as Sound; incompatible with video_list
    video_listAt most one clipBills as Video. refer_type: base or feature. keep_original_sound: yes or no
    metadata.image_listPublic image_url valuesOptional type of first_frame or end_frame; end_frame requires first_frame
    metadata.element_listSubject or role assetsurl plus optional type (for example image or video) and role
    watermarkBooleanOn/off only
    client_business_idOptional stringDocumented on the Chinese Omni reference as a top-level field (also accepted under metadata, top-level preferred). You can later query GET /v1/videos/generations/{client_business_id}

    Placeholder syntax is 1-based and must stay aligned with list order:

    SyntaxReferences
    <<<image_1>>>First item in metadata.image_list
    <<<video_1>>>First (and, per the Chinese reference, only) item in video_list
    <<<element_1>>>First item in metadata.element_list

    The English generation page illustrates <<<video_2>>> as list syntax. The Chinese reference caps video_list at one clip. Do not send a second reference video unless your account reference later says otherwise.

    There is still a practical way to build multi-shot and physically coherent clips:

    1. Lock the arc with first and end frames. Put the opening still in image_list with type: "first_frame" and the closing still with type: "end_frame". Mention both in the prompt (Transition from <<<image_1>>> to <<<image_2>>>) and describe the motion, gravity, and camera path between them.
    2. Anchor identity with element_list. Reuse the same subject URL and a stable role (for example "subject") across related jobs so clothing, face, and proportions do not drift when you change the camera description.
    3. Borrow motion with refer_type: "feature". Point <<<video_1>>> at a public motion reference and ask <<<element_1>>> to follow that motion. Use refer_type: "base" when you are editing the source clip itself (for example a background replacement).
    4. Chain jobs explicitly. The status document is not an Omni-specific last-frame API. If a later shot must start from a previous take, host a public still or download of that take and send it as the next first_frame. Persist each task id.

    Empty reference-list panels merging through a hexagonal gateway into one output frame

    Figure 1: image_list, video_list, and element_list (public URLs only) are submitted to POST /v1/videos/generations; poll the same task id and read result.data[0].url only after status is completed.

    For high-volume short-form drafts that do not need Omni lists, use kling-3.0-turbo. For a different Kling generation contract, see the Kling V4 Flash 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. Paths, model IDs, and the Bearer header stay the same.

    Step 1: cURL dispatch for a first-and-end-frame job

    bash
    curl -X POST "https://api.toapis.com/v1/videos/generations" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-v3-omni",
        "prompt": "Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
        "mode": "std",
        "duration": 5,
        "aspect_ratio": "16:9",
        "metadata": {
          "image_list": [
            {"image_url": "https://example.com/start.jpg", "type": "first_frame"},
            {"image_url": "https://example.com/end.jpg", "type": "end_frame"}
          ]
        }
      }'
    

    A text-only job omits metadata and the placeholders. A subject-plus-motion job uses video_list with refer_type: "feature" and metadata.element_list, and must not set audio: true.

    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_ID = "kling-v3-omni"
    DURATION_RANGE = range(3, 16)
    
    
    def dispatch_omni(
        prompt: str,
        *,
        model: str = DOCUMENTED_ID,
        mode: str = "std",
        duration: int = 5,
        aspect_ratio: str = "16:9",
        audio: bool = False,
        image_list: list[dict] | None = None,
        element_list: list[dict] | None = None,
        video_list: list[dict] | None = None,
        client_business_id: str | None = None,
    ) -> str:
        if model != DOCUMENTED_ID:
            raise ValueError("Send kling-v3-omni; kling-3-omni is not a documented public ID")
        if mode not in {"std", "pro"}:
            raise ValueError("mode must be std or pro")
        if duration not in DURATION_RANGE:
            raise ValueError("duration must be an integer from 3 to 15")
        if audio and video_list:
            raise ValueError("audio and video_list are mutually exclusive")
        if video_list and len(video_list) > 1:
            raise ValueError("video_list is documented as at most one clip")
        types = [item.get("type") for item in (image_list or [])]
        if "end_frame" in types and "first_frame" not in types:
            raise ValueError("end_frame requires first_frame")
        payload = {
            "model": model,
            "prompt": prompt,
            "mode": mode,
            "duration": duration,
            "aspect_ratio": aspect_ratio,
        }
        if audio:
            payload["audio"] = True
        if video_list:
            payload["video_list"] = video_list
        metadata = {}
        if image_list:
            metadata["image_list"] = image_list
        if element_list:
            metadata["element_list"] = element_list
        if metadata:
            payload["metadata"] = metadata
        if client_business_id:
            payload["client_business_id"] = client_business_id
        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 = 600) -> 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_omni(
            "Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
            image_list=[
                {"image_url": "https://example.com/start.jpg", "type": "first_frame"},
                {"image_url": "https://example.com/end.jpg", "type": "end_frame"},
            ],
        )
        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 placeholder or list-order change from a wording change. Download the file before expires_at; the status reference documents a 30-day retention window.


    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, or generation_timeout.

    HTTP or task stateCommon categoryRecommended action
    400Invalid field, placeholder/list mismatch, audio plus video_list, or end_frame without first_frameConfirm kling-v3-omni, that placeholder order matches each list, that media values are public URLs, and that mutually exclusive fields are not combined
    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; do not create a second job
    status: failedGeneration 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 official Chinese Omni reference publishes a billing map. Use it to choose a SKU family, then read the amount your account actually quotes.

    Request shapeBilling specification
    mode=std, audio=false, no video_list720P
    mode=pro, audio=false, no video_list1080P
    mode=std, audio=true720P+Sound
    mode=pro, audio=true1080P+Sound
    mode=std, with video_list720P+Video
    mode=pro, with video_list1080P+Video

    A 2026-11-18 fetch of the kling-v3-omni model-guide page showed a pricing reference of 12 credits / second and stated that final billing follows the current account quote. That page did not publish a USD per-second rate for Omni, and it did not break Sound or Video out as separate dollar figures. Do not convert credits to currency yourself, and do not reuse planning-draft rates such as $0.022/s.

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

    • Draft at the cheaper documented mode first. Iterate in std (720P) and a mid-range duration such as 5 seconds, keep a versioned prompt template, and change one reference list at a time.
    • A display price is not a channel guarantee. Confirm the ID, SKU, and availability with GET /v1/models?type=video and the live quote in your account before you forecast a shot list.
    • Control spend in the prompt layer: do not resubmit after a client timeout until you have checked task status. Official vendor contracts often add commitments or prepayment floors; ToAPIs billing is typically pay-as-you-go — confirm the active terms on your account.

    6. Frequently Asked Questions

    See the FAQ block in frontmatter. Summary: send kling-v3-omni, not kling-3-omni; there is no documented shots[] field; duration is 3–15 seconds and mode selects 720P or 1080P; audio and video_list cannot be combined; always poll the generations status path and persist the task id.


    7. Action Checklist

    • Create a key on the ToAPIs Developer Portal.
    • Confirm kling-v3-omni appears for your key via GET /v1/models?type=video — do not send kling-3-omni.
    • Smoke-test the cURL snippet with a first-and-end-frame image_list, mode: "std", and duration: 5.
    • Poll GET /v1/videos/generations/{id} with a bounded deadline, and download the result before expires_at.
    • Next: the Kling 3.0 Turbo automation guide for high-volume short-form drafts, the kling-v3-omni model guide for the live catalog status, and the Kling V4 Flash guide if you need a different Kling contract.

    Explore os modelos mencionados neste artigo

    KuaishouVIDEO

    kling-v3-omni

    Taxa atual: 12 credits /second
    Guia do modeloTestar no consoleObter chave de API
    KuaishouVIDEO

    Kling V3 Turbo

    Taxa atual: 16 credits /second
    Guia do modeloTestar no consoleObter chave de API
    KuaishouVIDEO

    kling-v3

    Taxa atual: 12 credits /second
    Guia do modeloTestar no consoleObter chave de API

    Artigos relacionados

    tutorial2026-11-18T10:00:00+08:007 min de leitura

    Kling 3.0 Turbo API: Architecting High-Volume Short-Form Video Automation

    A production guide to kling-3.0-turbo on ToAPIs: documented duration and resolution ranges, first-frame-only image input, a bounded poll loop, and high-volume short-form automation without unverified draft prices.

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Turbo
    tutorial2026-11-20T10:00:00+08:008 min de leitura

    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.

    TO
    ToAPIs Engineering & Evaluation Team
    #Wan 3.0
    tutorial2026-11-17T10:00:00+08:007 min de leitura

    Prática com a API do Grok-Video-3: tudo o que você precisa saber sobre o motor de vídeo da xAI

    Guia prático para chamar hoje o xAI Grok Video na ToAPIs: o catálogo público ainda lista grok-video-1.0 e grok-video-1.5, não grok-video-3, com o contrato atual de gerações, os modos e o caminho de sondagem.

    TO
    ToAPIs Engineering & Evaluation Team
    #Grok Video
    ToAPIs
    InícioToAPIs
    Gateway empresarial de API de IA. Acesse GPT-5, Claude, Gemini e mais de 200 modelos por uma única API unificada.

    Modelos populares

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

    Categorias de API

    • API de imagem com IA
    • API de vídeo com IA
    • API de texto para vídeo
    • API de imagem para vídeo
    Mostrar maisMostrar menos
    • API de edição de imagens com IA
    • API de LLM e raciocínio
    • Todas as ferramentas de API →

    Alternativas

    Alternativas
    • Alternativa ao Kie.ai
    • Alternativa ao Fal.ai
    • Alternativa ao OpenRouter
    • Alternativa ao Replicate
    • Alternativa ao Wavespeed AI
    • Todas as comparações →

    Guias em destaque

    Guias em destaque
    • Preços do Seedance 2.0 e 2.5
    • Guia da API Seedance mais barata
    • Guia de integração do MiniMax H3
    • Chave de API gratuita do Seedance 2
    • Início rápido da API Seedance 2
    • Todos os artigos técnicos →

    Desenvolvedores e plataforma

    Desenvolvedores e plataforma
    • Documentação da API
    • MCP
    • Preços
    • Playground de modelos
    • LLMs.txt
    • Falar com o suporte
    • Diretório de guias de modelos
    Entidade operadora:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    Sede social:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    PrivacidadeTermosUso aceitávelExclusão de dadosRetenção de dadosSubprocessadores e regiõesCobrança e reembolsosPolítica de CookiesMapa do siteSobre

    © 2026 ToAPIs. Todos os direitos reservados.