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. Grok Imagine 1.0 Video Generation API: Endpoints, Auth Scopes, and Error Handling
    Back to all posts
    tutorial2026-11-176 min read

    Grok Imagine 1.0 Video Generation API: Endpoints, Auth Scopes, and Error Handling

    The current ToAPIs Grok Imagine contract uses grok-imagine-video-official and grok-imagine-video-1.5-official: Bearer API-key auth, generations and extend endpoints, and the documented error and status handling — not a grok-imagine-1.0 ID or OAuth scope matrix.

    ToAPIs Engineering & Evaluation Team
    Grok ImagineVideo APIAuthenticationError HandlingTutorial
    TL;DR - Key Takeaways
    • There is no public catalog ID named grok-imagine-1.0. The documented official-channel IDs are grok-imagine-video-official (text, image, and multi-reference, plus extend) and grok-imagine-video-1.5-official (first-frame image-to-video only, up to 1080p, no extend).
    • Documented authentication is a Bearer API key on the Authorization header. This article did not find a public OAuth scope matrix (for example videos:write) for these endpoints.
    • Create jobs with POST /v1/videos/generations and poll GET /v1/videos/generations/{id}. Extend official-channel clips with POST /v1/videos/{video_id}/extend or POST /v1/videos/extend plus video_urls, for 2–10 extra seconds.
    • Upload local images with POST /v1/uploads/images and send public URLs only. official allows up to 7 images across image and reference_images; 1.5-official requires exactly one first-frame image and does not document video extend.
    • Output is billed per second by resolution tier; input images are billed per image; extend also bills the source video duration. Confirm live rates in your account — do not reuse draft unit prices.

    Grok Imagine 1.0 Video Generation API: Endpoints, Auth Scopes, and Error Handling

    Target Models: grok-imagine-video-official, grok-imagine-video-1.5-official
    Inference Endpoint: https://api.toapis.com/v1/videos/generations
    Related: Grok Video hands-on guide · OpenAI-compatible access · Official Imagine generation · Official Imagine extend


    1. TL;DR & Performance Overview

    • IDs: Requests titled around “Grok Imagine 1.0” need the strings ToAPIs actually publishes. The public catalog snapshot dated 2026-11-10 lists grok-imagine-video-official and grok-imagine-video-1.5-official (those two also appear under image-generation as well as openai-video). A 2026-11-17 check of a grok-imagine-1.0 docs path returned HTTP 404.
    • Auth: Send Authorization: Bearer $TOAPIS_API_KEY. The official pages do not document OAuth scopes, granular permission names, or a scope-discovery endpoint for these calls.
    • Endpoints: Create with POST /v1/videos/generations. Poll with GET /v1/videos/generations/{id}. Extend official-channel output with POST /v1/videos/{video_id}/extend, or POST /v1/videos/extend plus video_urls when you only have a public video URL. Upload stills with POST /v1/uploads/images.
    • Capabilities: grok-imagine-video-official covers text-to-video, image-to-video, and multi-reference generation at 480p or 720p, duration 1–15 seconds, and extend by 2–10 seconds. grok-imagine-video-1.5-official is first-frame image-to-video only, requires exactly one image, allows 1080p, and does not support extend.
    • Pricing shape (no fixed unit price on the reference pages): output billed per second by resolution; each input image billed per image; extend also bills the source video duration. Confirm live account rates.

    2. Endpoints, Authentication, and Model Contracts

    Official docs 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. Every path below uses the same Bearer header.

    ActionMethod and pathModel notes
    Upload a stillPOST /v1/uploads/imagesMultipart file. JPEG, PNG, WebP, or GIF, maximum 30 MB. Read data.url
    Create a videoPOST /v1/videos/generationsBoth official Imagine IDs
    Query statusGET /v1/videos/generations/{id}Same path for generate and extend tasks
    Extend from a prior taskPOST /v1/videos/{video_id}/extendgrok-imagine-video-official only. video_id is the previous generation task id
    Extend from a public URLPOST /v1/videos/extendSame official ID; video_urls is required when there is no path id
    Catalog IDDocumented jobsDurationResolutionImagesExtend
    grok-imagine-video-officialText-to-video, first-frame, and multi-reference1–15 seconds (default 8)480p, 720pOptional image plus reference_images; up to 7 total2–10 seconds (duration default 6)
    grok-imagine-video-1.5-officialFirst-frame image-to-video only1–15 seconds (default 8)480p, 720p, 1080pimage is required (exactly one first frame). Additional reference_images still count toward a 7-image totalNot supported

    Aspect-ratio values in the official Imagine references include 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, and 1:1. Send a value you have confirmed for that ID and channel.

    There is no documented public scope string to request “generate,” “extend,” or “upload” separately. Access is whatever the API key, user group, and channel configuration already allow. If a call fails with a permission or availability reason, check the key’s model list and the error reference rather than appending an invented scope query parameter.

    A credential node passing through a hexagonal gateway into three endpoint tiles

    Figure 1: One Bearer API key authorizes upload, generation or extend, and status polling; the official 1.5 ID does not add an extend branch.

    For the non-official Grok Video family (grok-video-1.0 / grok-video-1.5), see the hands-on Grok Video guide. Those IDs are a different contract and do not inherit this extend path.


    3. Production Implementation: cURL & Python

    Step 1: cURL — official-channel text-to-video

    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-imagine-video-official",
        "prompt": "A golden retriever running on a green field in sunny weather",
        "duration": 10,
        "resolution": "720p",
        "aspect_ratio": "16:9"
      }'
    

    A first-frame job on grok-imagine-video-1.5-official uses the same path, requires "image": "https://example.com/portrait.jpg", and may set "resolution": "1080p". Replace the example URL with a public address — upload the file first if it is local:

    bash
    curl -X POST "https://api.toapis.com/v1/uploads/images" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -F "file=@/path/to/first-frame.jpg"
    

    Step 2: Python — generate, poll, and optional extend

    python
    import os
    import time
    import requests
    
    API_KEY = os.environ["TOAPIS_API_KEY"]
    BASE = "https://api.toapis.com"
    HEADERS = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    
    
    def dispatch_imagine(
        prompt: str,
        *,
        model: str = "grok-imagine-video-official",
        duration: int = 10,
        resolution: str = "720p",
        aspect_ratio: str = "16:9",
        image_url: str | None = None,
        reference_images: list[str] | None = None,
    ) -> str:
        if model == "grok-imagine-video-1.5-official" and not image_url:
            raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
        payload = {
            "model": model,
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        }
        if image_url:
            payload["image"] = image_url
        if reference_images:
            payload["reference_images"] = reference_images
        res = requests.post(
            f"{BASE}/v1/videos/generations",
            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) -> dict:
        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={"Authorization": f"Bearer {API_KEY}"}, 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
            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")
    
    
    def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
        if not (2 <= duration <= 10):
            raise ValueError("official extend duration is documented as 2-10 seconds")
        res = requests.post(
            f"{BASE}/v1/videos/{source_task_id}/extend",
            headers=HEADERS,
            json={
                "model": "grok-imagine-video-official",
                "prompt": prompt,
                "duration": duration,
            },
            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 extend envelope: {data}")
        return task_id
    
    
    if __name__ == "__main__":
        task_id = dispatch_imagine(
            "A golden retriever running on a green field in sunny weather",
            duration=10,
            resolution="720p",
        )
        print("Task:", task_id)
        result = poll_task(task_id)
        print("Video:", result["result"]["data"][0]["url"])
    

    To extend from a public MP4 instead of a task id, POST /v1/videos/extend with the same official model, prompt, duration, and a video_urls list. Do not call extend with grok-imagine-video-1.5-official.


    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. The error reference distinguishes request errors, failed-task error.reason values, and webhook payloads.

    HTTP or task stateCommon categoryRecommended action
    400Invalid field, missing required image on 1.5-official, image-count overflow, or extend sent to a model that does not support itCheck the exact official ID, duration (1–15 on generate, 2–10 on extend), resolution (1080p only on 1.5-official), and that all media values are public URLs
    401Missing or invalid API keyRotate the key and confirm Authorization: Bearer. Do not add an undocumented scope parameter as a workaround
    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: queued or in_progressNot an errorWait and poll again
    status: failed with content_policy_rejectedSafety or copyright reviewInspect prompt and every reference asset; compliant input can still produce a rejected output
    status: failed with insufficient_user_balance or token_quota_exceededWallet or token allowanceCheck both balance and periodic limits
    status: failed with generation_timeout, model_unavailable, or service_busyUpstream timeout or availabilityCheck the existing id first; then retry with backoff only if the task is terminal

    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 Imagine generation and extend pages describe a billing shape, not a fixed public unit price:

    Estimated cost=(output seconds×resolution rate)+(input images×per-image rate)+(extend source seconds×per-second rate)\text{Estimated cost} = (\text{output seconds} \times \text{resolution rate}) + (\text{input images} \times \text{per-image rate}) + (\text{extend source seconds} \times \text{per-second rate})Estimated cost=(output seconds×resolution rate)+(input images×per-image rate)+(extend source seconds×per-second rate)

    Use the rates returned for your account and SKU, not draft numbers.

    • grok-imagine-video-1.5-official always includes one input-image charge, because a first-frame image is required.
    • Extend is not a free continuation. Official extend billing includes generated extension seconds and the source video duration. Stacked extends therefore charge the growing source length again — confirm that behavior against a live quote before you build a loop.
    • Do not reuse planning-draft unit prices or SLA figures. Official vendor reference rows on the ToAPIs pricing page are display-only and may not match account billing.
    • Draft at 720p and a mid-range duration, change one variable at a time, and never resubmit after a client timeout until you have checked task status.

    6. Frequently Asked Questions

    See the FAQ block in frontmatter. Summary: send grok-imagine-video-official or grok-imagine-video-1.5-official, not grok-imagine-1.0; auth is a Bearer API key with no public OAuth scope matrix; 1.5-official is first-frame only and cannot extend; extend duration is 2–10 seconds and bills the source length as well; always distinguish HTTP errors from status: failed.


    7. Action Checklist

    • Create a key on the ToAPIs Developer Portal.
    • Confirm grok-imagine-video-official or grok-imagine-video-1.5-official appears for your key via GET /v1/models?type=video.
    • Smoke-test a 720p official-channel generation, poll GET /v1/videos/generations/{id}, and download the file before expires_at.
    • If you need a continuation, extend only with grok-imagine-video-official and a 2–10 second duration, then confirm the quote includes source-duration billing.
    • Next: the official Imagine model guide and the official Imagine 1.5 model guide for live catalog status, and the hands-on Grok Video guide if you meant the non-official grok-video-* family.

    Explore Models Mentioned in This Post

    xAIVIDEO

    grok-imagine-video-official

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

    grok-imagine-video-1.5-official

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

    Related Articles

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