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. How to Access Grok Video 3 API via OpenAI-Compatible Endpoints
    Back to all posts
    tutorial2026-11-175 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.

    ToAPIs Engineering & Evaluation Team
    Grok VideoOpenAI CompatibleVideo APIAPI GatewayTutorial
    TL;DR - Key Takeaways
    • ToAPIs documents a unified OpenAI-compatible /v1 base URL and Bearer API key. Grok Video IDs currently listed for that openai-video endpoint are grok-video-1.0 and grok-video-1.5, not grok-video-3.
    • List video models with GET /v1/models?type=video. The default models list returns text models only; omitting type will hide Grok Video IDs.
    • Create and poll video jobs with POST /v1/videos/generations and GET /v1/videos/generations/{id}. This is the documented video contract. Do not assume an OpenAI Videos SDK method such as client.videos.create exists on ToAPIs unless your account docs say so.
    • Keep the same Authorization header across chat, uploads, and video. For local assets, upload with POST /v1/uploads/images and pass the returned public URL.
    • Confirm the exact model string and live rate in your account. A compatible base URL does not invent an unpublished model ID or a fixed unit price.

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

    Target Models: grok-video-1.5, grok-video-1.0
    Inference Endpoint: https://api.toapis.com/v1/videos/generations
    Related: Grok Video hands-on guide · Grok Imagine official-channel API · Chatbox OpenAI-compatible setup · List models


    1. TL;DR & Performance Overview

    • What “OpenAI-compatible” means here: ToAPIs documents a single /v1 origin, Bearer authentication, and an OpenAI-style models list and chat completions API. Public Grok Video IDs are registered on the catalog’s openai-video endpoint family. That does not mean an unpublished grok-video-3 ID will work, and it does not by itself document an OpenAI Videos SDK method.
    • IDs: Use grok-video-1.5 or grok-video-1.0 after they appear for your key in GET /v1/models?type=video. The public catalog snapshot dated 2026-11-10 does not list grok-video-3.
    • Video path: Create with POST /v1/videos/generations. Poll with GET /v1/videos/generations/{id}. Official examples use https://toapis.com (and https://toapis.cn for mainland China). This series also uses https://api.toapis.com.
    • Shared auth: One API key in Authorization: Bearer. There is no separate public OAuth scope document for these video calls.
    • Client choice: Use the OpenAI SDK against base_url="https://api.toapis.com/v1" for chat-style work and for a familiar key/origin setup. For Grok Video, this guide uses the documented REST JSON body so video_generation_mode and image URL fields stay explicit.

    2. Compatible Origin, Model List, and Video Paths

    Keep the origin, the /v1 prefix, and the key together. Mixing a ToAPIs key with https://api.openai.com/v1, or a ToAPIs origin with a vendor-native Grok path, is a different — and undocumented — setup.

    StepDocumented pathNotes
    List modelsGET /v1/models?type=videoDefault GET /v1/models returns text models only. Use type=video or type=all
    Upload a local imagePOST /v1/uploads/images (multipart file)Read data.url. Do not send base64 on the generation call
    Create a Grok Video jobPOST /v1/videos/generationsBody includes model, prompt, and the 1.5 mode/media fields
    Poll statusGET /v1/videos/generations/{id}Terminal states are completed and failed
    Chat (not video)POST /v1/chat/completionsShares the origin and key only

    On grok-video-1.5, set video_generation_mode to text_to_video, first_frame_image_to_video, or reference_images_to_video so the JSON matches the media you send. The field-level contract is in the hands-on Grok Video guide and the Grok Video 1.5 API reference.

    A compatible client panel connecting through a hexagonal gateway to submit and poll paths

    Figure 1: Point the client at a ToAPIs /v1 origin, discover grok-video-1.5 or grok-video-1.0 with the models list, then submit and poll on /v1/videos/generations — not on chat/completions.

    If you are configuring a desktop client rather than application code, the Chatbox setup guide covers the host-field pattern for chat. Do not expect that same chat path to return a video file.


    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: Discover the ID, then dispatch with cURL

    bash
    curl -sS "https://api.toapis.com/v1/models?type=video" \
      -H "Authorization: Bearer $TOAPIS_API_KEY"
    
    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"
      }'
    

    Inspect the models list for the exact id string before you hard-code it. If grok-video-3 is absent, do not send it.

    Step 2: Python — shared origin, REST video calls

    The OpenAI SDK is shown only for the shared base_url and API key. Video create and poll stay on the documented generations paths so the 1.5 body fields are not lost in an unofficial client mapping.

    python
    import os
    import time
    import requests
    from openai import OpenAI
    
    API_KEY = os.environ["TOAPIS_API_KEY"]
    BASE = "https://api.toapis.com"
    HEADERS = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    
    # Shared origin and key. Use this client for chat completions; do not assume
    # a videos.create mapping unless your account docs define one.
    client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
    
    
    def list_video_model_ids() -> list[str]:
        res = requests.get(
            f"{BASE}/v1/models",
            headers=HEADERS,
            params={"type": "video"},
            timeout=30,
        )
        res.raise_for_status()
        data = res.json()
        items = data.get("data") or data.get("models") or []
        return [item.get("id") or item.get("name") for item in items if item]
    
    
    def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
        available = set(list_video_model_ids())
        if available and model not in available:
            raise ValueError(f"{model} is not in this key's video model list")
        res = requests.post(
            f"{BASE}/v1/videos/generations",
            headers=HEADERS,
            json={
                "model": model,
                "prompt": prompt,
                "video_generation_mode": "text_to_video",
                "duration": 8,
                "resolution": "720p",
                "aspect_ratio": "16:9",
            },
            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__":
        print("Video models (excerpt):", list_video_model_ids()[:20])
        task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
        print("Task:", task_id)
        print("Video:", poll_task(task_id))
    

    If the list call returns an unexpected envelope, log the raw JSON and align the parser with the List models page for your account. Do not invent a fallback that sends grok-video-3 when the ID is missing.


    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.

    HTTP or task stateCommon categoryRecommended action
    400Unknown model ID, mode/media mismatch, or a video body sent to a chat pathConfirm the ID in GET /v1/models?type=video, that you posted to /v1/videos/generations, and that 1.5 jobs set a matching video_generation_mode
    401Missing or invalid API keyUse a ToAPIs key, not an OpenAI platform key, and confirm the Bearer header
    404Wrong origin, missing /v1, or an invented path such as /videos/tasks/{id}Switch to GET /v1/videos/generations/{id} on the origin you used to submit
    429Rate or concurrency limitHonor Retry-After when present; back off with jitter
    5xx or client timeoutTemporary gateway or upstream issueQuery the existing task id before resubmitting
    status: failedGeneration did not succeedRead error.code and error.message. 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

    • Compatibility does not change the billable SKU. You are billed for the catalog model ID you send (grok-video-1.5 or grok-video-1.0), not for “using the OpenAI SDK.”
    • Do not reuse planning-draft unit prices. The Grok Video 1.5 reference does not guarantee a fixed per-second price. Official vendor reference rows on the ToAPIs pricing page are display-only and may not match account billing.
    • Failed discovery is cheap; duplicate generation is not. Cache the models list for a short period, but always check task status after a client timeout before you create another job.
    • 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: a compatible base URL does not unlock grok-video-3; include /v1 once; poll /v1/videos/generations/{id}; do not assume an SDK videos.create helper; chat completions will not return an MP4.


    7. Action Checklist

    • Create a key on the ToAPIs Developer Portal.
    • Point your client at https://api.toapis.com/v1 (or https://toapis.cn/v1 in mainland China) with Authorization: Bearer.
    • Call GET /v1/models?type=video and record the exact Grok Video IDs your key can see.
    • Smoke-test POST /v1/videos/generations with grok-video-1.5 and video_generation_mode: "text_to_video", then poll the same id.
    • Next: the hands-on Grok Video guide for mode and image-field details, and the Grok Video 1.5 model guide for live catalog status.

    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: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
    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:007 min read

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