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. Hands-on with Grok-Video-3 API: Everything You Need to Know About xAI's Video Engine
    Back to all posts
    tutorial2026-11-176 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.

    ToAPIs Engineering & Evaluation Team
    Grok VideoVideo APIxAIText-to-VideoTutorial
    TL;DR - Key Takeaways
    • As of the public catalog snapshot dated 2026-11-10, and after a 2026-11-17 check of the docs and model-guide pages, there is no public ToAPIs model ID named grok-video-3. The documented Grok Video IDs are grok-video-1.0 and grok-video-1.5.
    • Submit jobs to POST /v1/videos/generations with a Bearer API key. Persist the task id and poll GET /v1/videos/generations/{id}. Do not call an undocumented /videos/tasks path.
    • grok-video-1.5 documents three explicit modes: text_to_video, first_frame_image_to_video, and reference_images_to_video. Set video_generation_mode to match the media you actually send.
    • Images must be public http(s) URLs. Upload local files with POST /v1/uploads/images first; base64 is not accepted on these generation APIs.
    • Do not reuse unverified per-second prices or SLA figures from planning drafts. Confirm the live rate and channel support in your account before you forecast a shot list.

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

    Target Models: grok-video-1.5, grok-video-1.0
    Inference Endpoint: https://api.toapis.com/v1/videos/generations
    Related: OpenAI-compatible access · Grok Imagine official-channel API · Hailuo 2.3 video guide · Grok Video 1.5 reference


    1. TL;DR & Performance Overview

    • Catalog first: Requests for a hands-on Grok Video 3 integration still have to start from the IDs ToAPIs actually publishes. The public production catalog snapshot dated 2026-11-10 lists grok-video-1.0 and grok-video-1.5 on the openai-video endpoint. A 2026-11-17 check of the grok-video-3 documentation and model-guide URLs returned HTTP 404.
    • Contract: Submit asynchronously to POST /v1/videos/generations, then poll GET /v1/videos/generations/{id} until completed or failed. 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: grok-video-1.5 documents text_to_video, first_frame_image_to_video, and reference_images_to_video. Set video_generation_mode explicitly so a single reference image is not treated as a legacy first-frame job.
    • Media: Send public http:// or https:// URLs only. Upload local files with POST /v1/uploads/images and use the returned data.url. Do not send base64.
    • Unverified claims to drop: Planning drafts that quote a grok-video-3 ID, a 99.95% SLA, a fixed $0.030–$0.038 per-second rate, or a future audio ship date are not current ToAPIs documentation. Confirm live rates and channel support in your account.

    2. Current Grok Video IDs and Generation Modes

    Use the public model name in the model field. Do not substitute a supplier-native name, a URL slug, or an unpublished grok-video-3 string.

    Catalog IDDocumented jobsDuration (docs)ResolutionImage inputs
    grok-video-1.5Text, first-frame, or 1–7 reference images, selected with video_generation_modeInteger 1–15 seconds480p or 720p in reference mode; text and first-frame may use 1080p when the channel supports itFirst-frame: exactly one image or input_reference. Reference mode: 1–7 reference_images
    grok-video-1.0Text-to-video and image-to-videoGeneration reference: 1–15 seconds (default 8). Model guide / playground: a 6-second cap on the currently available variant480p, 720pOptional image plus reference_images; up to 8 images total

    For grok-video-1.5, new integrations should set the mode explicitly:

    video_generation_modeRequired inputMust omit
    text_to_videoNon-empty promptAny image field
    first_frame_image_to_videoExactly one first frame in image or input_referenceConflicting values in both aliases; do not also send a reference list unless the reference for your account says otherwise
    reference_images_to_videoprompt plus 1–7 reference_images (strings or {"url":"..."} objects)Relying on a single reference_images entry without this mode — legacy single-image input stays first-frame behavior

    A successful price quote does not guarantee that a generation channel is open. Modes are available only when enabled on a compatible channel; unsupported combinations can be rejected before a task is created.

    Common aspect-ratio values in the Grok Video references are 16:9, 9:16, 3:2, 2:3, and 1:1. Availability still depends on the channel, so send a value you have confirmed for that ID.

    Empty input frames moving through a hexagonal gateway into one output frame

    Figure 1: Submit a prompt (and optional public image URLs) to POST /v1/videos/generations, poll the same task id, and read result.data[0].url only after status is completed.

    If you need official-channel Grok Imagine features such as video extend, that is a different ID family — see the Imagine official-channel guide. For a second video contract with a different duration matrix, see the Hailuo 2.3 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 grok-video-1.5

    bash
    curl -X POST "https://api.toapis.com/v1/videos/generations" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "grok-video-1.5",
        "prompt": "A cinematic product shot with a slow camera push-in",
        "video_generation_mode": "text_to_video",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "16:9"
      }'
    

    A first-frame job uses the same path with "video_generation_mode": "first_frame_image_to_video" and an image URL. A reference-image job sets "video_generation_mode": "reference_images_to_video" and a reference_images list, and keeps resolution at 480p or 720p.

    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",
    }
    
    
    def dispatch_grok_video(
        prompt: str,
        *,
        model: str = "grok-video-1.5",
        mode: str = "text_to_video",
        duration: int = 8,
        resolution: str = "720p",
        aspect_ratio: str = "16:9",
        image_url: str | None = None,
        reference_images: list[str] | None = None,
    ) -> str:
        if model == "grok-video-3":
            raise ValueError("grok-video-3 is not a current public catalog ID")
        if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
            raise ValueError("reference mode is documented as 480p or 720p")
        payload = {
            "model": model,
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        }
        if model == "grok-video-1.5":
            payload["video_generation_mode"] = mode
        if mode == "text_to_video" and (image_url or reference_images):
            raise ValueError("text_to_video rejects image fields")
        if mode == "first_frame_image_to_video":
            if not image_url:
                raise ValueError("first-frame mode requires exactly one image URL")
            payload["image"] = image_url
        if mode == "reference_images_to_video":
            refs = reference_images or []
            if not (1 <= len(refs) <= 7):
                raise ValueError("reference mode requires 1-7 image URLs")
            payload["reference_images"] = refs
        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_grok_video(
            "A cinematic product shot with a slow camera push-in",
            mode="text_to_video",
            duration=8,
            resolution="720p",
        )
        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 model or mode 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, mode/media mismatch, or unsupported combinationCheck the exact catalog ID, that video_generation_mode matches the image fields, that reference mode stays at 480p or 720p, and that image values are public URLs
    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

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

    • Do not reuse planning-draft unit prices. The grok-video-1.5 API reference states that pricing follows the current account and SKU configuration and that the page does not guarantee a fixed per-second price. Official vendor reference rows on the ToAPIs pricing page are display-only and may not match what your account is billed.
    • A quote is not a channel guarantee. The 1.5 reference notes that a successful price quote does not mean a generation channel is available.
    • Control spend in the prompt layer: draft at 720p and a mid-range duration such as 8 seconds, keep a versioned template, change one variable at a time, and do not resubmit after a client timeout until you have checked task status.
    • Official vendor contracts often add annual commitments, seat quotas, and 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: grok-video-3 is not a current public catalog ID; start from grok-video-1.5 or grok-video-1.0; treat the 1.0 duration cap as a channel-specific check; synchronized audio is not documented; always poll the generations status path and persist the task id.


    7. Action Checklist

    • Create a key on the ToAPIs Developer Portal.
    • Confirm grok-video-1.5 or grok-video-1.0 appears for your key via GET /v1/models?type=video — do not send grok-video-3 unless it later appears in that list and in the API reference.
    • Smoke-test the cURL snippet with video_generation_mode: "text_to_video", duration: 8, and resolution: "720p".
    • Poll GET /v1/videos/generations/{id} with a bounded deadline, and download the result before expires_at.
    • Next: the OpenAI-compatible access guide if you are pointing an existing client at ToAPIs, the Grok Video 1.5 model guide for live catalog status, and the Grok Video 1.0 model guide before you rely on a duration above 6 seconds on that ID.

    Explore Models Mentioned in This Post

    xAIVIDEO

    grok-video-1.0

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

    Grok Video 1.5

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

    Related Articles

    tutorial2026-11-17T10:00:00+08:005 min read

    How to Access Grok Video 3 API via OpenAI-Compatible Endpoints

    Point an OpenAI-compatible client at ToAPIs to call the current Grok Video catalog IDs: shared Bearer auth and /v1 base URL, with video jobs on POST /v1/videos/generations rather than an unpublished grok-video-3 path.

    TO
    ToAPIs Engineering & Evaluation Team
    #Grok Video
    tutorial2026-11-20T10:00:00+08:008 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.

    TO
    ToAPIs Engineering & Evaluation Team
    #Wan 3.0
    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
    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.