How to Use the Grok Imagine 1.5 API: A Complete Guide to Endpoints, Pricing & Code Examples

You found the Grok Imagine 1.5 model, tested it on the web interface, got impressive clips — and now you want to call it from code. You set up your API key, found the endpoint, and sent your first request. Then nothing happened. No video. No error. Just a JSON object with a request_id staring back at you.

If you've been through this, you're not alone. "Grok Imagine 1.5 API" gets 850 monthly searches — and the top results point to official xAI docs, third-party platform pages, and blog posts that each cover a different piece of the puzzle. The grok-imagine-video-1.5 model is xAI's image-to-video generation model released in early 2026, capable of producing up to 15-second video clips with synchronized audio from a single image and text prompt. As more teams move from experimenting on the web interface to building production pipelines in mid-2026, mastering the async API workflow has become the critical skill that separates a working integration from a stalled project. The API workflow — submit, poll, retrieve — is fundamentally different from the synchronous APIs most developers are used to, and that single detail accounts for most first-time integration failures.

We've tested the xAI API across Python SDK, cURL, and Vercel AI Gateway, referenced the official xAI Imagine docs and pricing page, and cross-checked against third-party providers including Cloudflare Workers AI and AI/ML API. This guide covers every endpoint, every parameter, the real-world cost per video, and the async workflow that trips up most first-time callers. By the end, you'll be able to make your first successful API call, understand how polling works, and know which provider — direct xAI or third-party — fits your use case.

What Is the Grok Imagine 1.5 API? (And Why It's Not Like Standard APIs)

The Grok Imagine 1.5 API is xAI's programmatic interface to the grok-imagine-video-1.5 model. Unlike the web interface at grok.com/imagine or third-party playgrounds, the API lets you integrate video generation directly into your application, automation pipeline, or creative tool.

Here's what the API can do:

Here's an intuitive way to think about it: the model is a motion interpreter, not a video recorder. You give it a static starting frame (your image) and a motion script (your prompt), and it predicts what happens next — frame by frame — the way an animator works from a single keyframe. It has learned how objects move, how light shifts, and how cameras behave by training on millions of video clips. That's why a specific motion prompt like "slow cinematic push-in, sunlight filtering through leaves" produces dramatically better results than "make this move." The prompt tells the model which of its learned motion patterns to apply to your specific starting image.

There are two model identifiers you'll encounter:

Rule of thumb: Use grok-imagine-video-1.5 for production workloads. Use grok-imagine-video-1.5-preview if you want early access to new capabilities and can tolerate occasional breaking changes.

Once you know what the model can do, the next practical question is: what will each generation actually cost in production?

Grok Imagine 1.5 API Pricing: What Each Video Actually Costs

One of the biggest questions developers ask before integrating is "how much will this cost per video?" The xAI API pricing is straightforward — you pay per second of output video at your chosen resolution, plus a flat fee per input image.

There is also a $0.01 per input image fee applied to every generation request.

So a 6-second 720p video with one input image costs: (6 × $0.14) + $0.01 = $0.85. A 15-second 1080p video costs: (15 × $0.25) + $0.01 = $3.76.

What about rate limits? The xAI API enforces a rate limit of 1 request per second per API key for video generation. If you need higher throughput, you'll need to either queue requests or distribute across multiple API keys. Third-party providers like Vercel AI Gateway and OpenRouter may offer different rate limits — we cover this in the provider comparison section below.

With the pricing and limits clear, let's make sure you have everything set up for your first API call.

Before You Start: 3 Things Your First API Call Needs

To make your first API call, prepare these three things:

1. An xAI API key — Sign up at console.x.ai to generate one. You'll need a billing method attached; the free tier does not include API access for video generation.
2. A source image URL — The image must be publicly accessible via HTTPS. Supported formats include PNG, JPEG, and WebP. For best results, use a clean, well-lit image without heavy compression artifacts.
3. An HTTP client or SDK — You can use cURL, Python (with xai-sdk or plain requests), Node.js (with @ai-sdk/xai or openai), or any REST client like Postman.

Get Your xAI API Key: Setup Authentication in 3 Steps

Step 1: Generate your API key Go to platform.x.ai, navigate to the API keys section, and create a new key. Copy it immediately — you won't be able to see it again.

Step 2: Set it as an environment variable

export XAI_API_KEY="your-api-key-here"

Step 3: Test your key

curl -s https://api.x.ai/v1/models \
  -H "Authorization: Bearer $XAI_API_KEY" | head -20

If your key is valid, you'll receive a JSON list of available models. If you get a 401, double-check that your key was copied correctly and that billing is set up.

Security note: Never hardcode your API key in source code, commit it to version control, or expose it in client-side JavaScript. Use environment variables or a secrets manager.

Making Your First API Call: Code Examples

The Grok Imagine 1.5 API is asynchronous — you submit a generation request, receive a request_id, and then poll for the result. Here's how it works in the three most common environments.

cURL (Quick Test)

Submit the generation:

curl -s -X POST "https://api.x.ai/v1/videos/generations" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "Slow cinematic push-in as sunlight filters through the trees, birds take flight",
    "image": {
      "url": "https://example.com/your-image.jpg"
    },
    "duration": 6,
    "resolution": "720p"
  }'

The response will look like this:

{
  "id": "vreq_abc123def456",
  "status": "queued",
  "created_at": "2026-07-08T10:00:00Z"
}

Save the id — you'll need it to retrieve your video. Poll the status endpoint every 5–10 seconds:

curl -s "https://api.x.ai/v1/videos/vreq_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

When the status changes to "done", the response will include a video_url field pointing to your generated clip.

Python (xAI SDK)

The official xai-sdk Python package provides a clean interface:

pip install xai-sdk

import os
import xai_sdk
import time

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Submit the generation
response = client.video.generate(
    model="grok-imagine-video-1.5",
    prompt="A flowing river with autumn leaves drifting downstream, golden hour lighting",
    image_url="https://example.com/your-image.jpg",
    duration=6,
    resolution="720p"
)

request_id = response.id
print(f"Generation submitted: {request_id}")

# Poll for results
while True:
    result = client.video.get_generation(request_id)
    print(f"Status: {result.status}")
    if result.status == "done":
        print(f"Video URL: {result.video_url}")
        print(f"Audio URL: {result.audio_url}")
        break
    elif result.status == "failed":
        print(f"Generation failed: {result.error}")
        break
    time.sleep(5)

Node.js (Vercel AI SDK)

If you're using the Vercel AI SDK with the xAI provider:

npm install @ai-sdk/xai

import { xai } from '@ai-sdk/xai';
import { generateVideo } from 'ai';
import { writeFile } from 'fs/promises';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'Waves crashing on a rocky shore, spray catching the morning light',
  // Note: @ai-sdk/xai handles polling internally
});

// `video` contains the generated video as a base64-encoded string
const buffer = Buffer.from(video.base64, 'base64');
await writeFile('output.mp4', buffer);
console.log('Video saved to output.mp4');

Rule of thumb: For quick testing, use cURL. For production Python apps, use the xai-sdk. For JavaScript/TypeScript projects, use @ai-sdk/xai which handles the async polling lifecycle automatically.

All three examples above rely on the same asynchronous pattern under the hood. Understanding why it works this way — and what's happening between submission and download — is key to building a reliable integration.

Understanding the Async Workflow: Why It Works This Way

Video generation is computationally expensive — even xAI's optimized model takes approximately 25 seconds to produce a 6-second 720p clip. That's far too slow for a synchronous HTTP response. So the API uses an async submission + polling pattern:

You                      xAI API
  │                         │
  │── POST /v1/videos/ ──→  │
  │     generations         │
  │←── { id, "queued" } ──  │
  │                         │── [queue → process → encode]
  │                         │
  │── GET /v1/videos/{id} ─→│  (poll every 5s)
  │←── { status: "done" } ─│
  │     video_url           │

Status values you'll encounter:

Estimated wait times:

• 480p / 6 seconds: ~15–20 seconds
• 720p / 6 seconds: ~20–30 seconds
• 1080p / 10 seconds: ~40–60 seconds
• 1080p / 15 seconds: ~60–90 seconds

Now that you understand the submission and polling flow, here is every parameter available on the generation endpoint — including the fields that are easy to get wrong.

Complete Parameters Reference

Here is every parameter accepted by the POST /v1/videos/generations endpoint:

Parameter gotchas:

• reference_images is not supported on grok-imagine-video-1.5-preview — sending it returns a 400 error. The GA model grok-imagine-video-1.5 also does not support reference images; only the full grok-imagine-video suite model does.
• If image.url points to a private resource (requires authentication), the API will return a 400 error. The image must be publicly accessible.
• duration values over 15 seconds are silently capped at 15. If you need longer videos, generate multiple clips and stitch them client-side.

With the direct API workflow and parameters clear, let's look at an alternative path: accessing the Grok Imagine 1.5 model through third-party platforms that may offer different pricing, rate limits, or convenience features.

Grok Imagine 1.5 API Through Third-Party Providers

You don't have to call xAI directly. Several platforms offer the Grok Imagine 1.5 model through their own APIs, often with different pricing, rate limits, or convenience features.

Vercel AI Gateway

Vercel's AI Gateway provides a unified API surface across multiple model providers, including xAI.

• Model slug: xai/grok-imagine-video-1.5 or xai/grok-imagine-video-1.5-preview
• Pricing: xAI's base pricing + Vercel's usage fee (typically ~10–15% markup)
• Rate limits: Dependent on your Vercel plan
• Best for: Teams already on Vercel who want consolidated billing and observability
• Connection: https://vercel.com/ai-gateway/models/grok-imagine-video-1.5

AI/ML API

Available as x-ai/grok-imagine-video-1.5-preview through the AI/ML API platform.

• Pricing: Starts at $0.15/second for 720p (slightly higher than direct xAI pricing)
• Rate limits: 5 requests/second (higher than xAI's 1 req/sec)
• Best for: Users who need higher throughput than xAI's native rate limit
• Docs: https://docs.aimlapi.com/api-references/video-models/xai/grok-imagine-video-1.5-preview

Cloudflare Workers AI

Available via @cf/xai/grok-imagine-video-1.5-preview on Cloudflare's global network.

• Pricing: Included in Cloudflare Workers AI subscription (no per-second markup)
• Rate limits: Based on your Workers AI plan tier
• Best for: Existing Cloudflare customers who want to keep inference on the edge
• Docs: https://developers.cloudflare.com/ai/models/xai/grok-imagine-video-1.5-preview/

OpenRouter

OpenRouter aggregates multiple model providers and offers the model through their API.

• Model slug: x-ai/grok-imagine-video-1.5 or x-ai/grok-imagine-video-1.5-preview
• Pricing: Variable — may be higher than direct xAI due to aggregation fees
• Best for: Users who want to switch between multiple model providers through a single API key
• Rate limits: 20 requests/minute

Direct API vs Third-Party: Which Should You Use?

Rule of thumb: Start with the direct xAI API if you want the lowest per-video cost and are building a dedicated integration. Use a third-party provider if you need higher rate limits, are already on their platform, or want consolidated billing across multiple AI models.

No matter which provider you choose, you'll eventually run into edge cases and errors. Here is how to diagnose and fix the most common ones.

Common API Errors and How to Fix Them

400 Bad Request — Invalid Parameters

{"error": {"message": "Invalid parameter: reference_images is not supported on model grok-imagine-video-1.5-preview", "type": "invalid_request_error"}}

• Root cause: The request includes a parameter that the selected model variant does not support. The most common culprit is reference_images, which is not available on grok-imagine-video-1.5 or its preview. Another frequent cause: the image.url field points to a private or authenticated resource instead of a publicly accessible URL.
• Fix: Remove the unsupported parameter. Stick to the parameters listed in the reference table above — those are guaranteed to work on both model variants. For the image.url, verify the URL renders in an incognito browser window before sending it to the API.
• Verified when: The API returns a 202 instead of a 400 after making the fix.

401 Unauthorized — Invalid API Key

{"error": {"message": "Incorrect API key provided", "type": "authentication_error"}}

• Root cause: The API key in the Authorization header is incorrect, expired, or belongs to an account without billing configured for video generation.
• Fix: Go to console.x.ai, regenerate your API key, and set it as an environment variable again. Verify there are no trailing spaces or newline characters. Run the cURL key test from the setup section above — a non-401 response confirms the key works.
• Verified when: The model list endpoint returns a 200 with available models.

429 Too Many Requests — Rate Limit Hit

{"error": {"message": "Rate limit exceeded: 1 request per second", "type": "rate_limit_error"}}

• Root cause: You've sent more than one request within a one-second window on the same API key. The xAI API enforces a sliding-window rate limit of 1 request per second for video generation.
• Fix: Add a minimum 1-second delay between consecutive requests using time.sleep(1) (Python), setTimeout (Node.js), or a queue-based submission system. If you need higher throughput, distribute work across multiple API keys or switch to AI/ML API (5 req/sec).
• Verified when: You can submit two consecutive requests 1 second apart and both return a 202 instead of a 429.

500 Internal Server Error — Transient Failure

{"error": {"message": "Internal server error", "type": "server_error"}}

• Root cause: An unexpected server-side error during queueing, model inference, or encoding. This is typically transient and not caused by your request parameters.
• Fix: Wait 10–15 seconds and retry the same request. If the error persists for more than 5 minutes, check the xAI status page for reported incidents.
• Verified when: A retried request returns a 202 or the status endpoint returns done.

Rule of thumb for error handling: Implement exponential backoff — wait 5 seconds after the first failure, 10 after the second, 20 after the third, then give up after 5 retries. Most transient errors resolve within two retries. Always check the error type field rather than parsing the message string, as message text may change between API versions.

5 Production Best Practices: Retry Logic, Webhooks, Cost Control, and Caching

1. Implement Proper Retry Logic

Not every API call succeeds on the first attempt. Plan for failures:

import time
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=4, max=30))
def generate_video_with_retry(client, prompt, image_url, duration=6):
    response = client.video.generate(
        model="grok-imagine-video-1.5",
        prompt=prompt,
        image_url=image_url,
        duration=duration,
        resolution="720p"
    )
    return response

2. Use Webhooks Instead of Polling

If your application can accept incoming POST requests, set the callback_url parameter. The API will POST the generation result to your endpoint when it's ready, eliminating the need for polling:

{
  "model": "grok-imagine-video-1.5",
  "prompt": "...",
  "image": {"url": "https://..."},
  "callback_url": "https://your-app.com/webhooks/xai-video-complete"
}

The callback payload includes the same fields as the polling response, plus a signature header you can verify to confirm the request came from xAI.

3. Estimate Your Monthly Cost

Before integrating into production, calculate your expected usage:

Monthly cost = (Average videos/day × 30) × (duration × price_per_second + $0.01/image)

Example:
  100 videos/day × 30 days = 3,000 videos/month
  3,000 × (6 sec × $0.14 + $0.01) = 3,000 × $0.85 = $2,550/month

For 3,000 clips per month at 6 seconds 720p, budget about $2,550 for the direct xAI API. Switching to 480p drops this to $1,470, while 1080p brings it to $4,530.

4. Cache Generated Videos

Store the video_url results with their metadata and generation parameters. If you generate the same scene multiple times with small variations, caching avoids redundant API calls. Consider using a simple key-value store keyed by a hash of (prompt + image_url + duration + resolution).

5. Follow Responsible Usage Guidelines

Using the Grok Imagine 1.5 API comes with responsibilities. Working through these four areas up front saves you from costly compliance surprises later.

Content Safety: Filter Early, Not Late

Every submission is subject to xAI's automated content moderation. Prompts and images depicting violence, hate speech, adult content, or copyrighted material will be rejected before generation starts — but relying solely on post-generation rejection wastes both time and money. Action: Review xAI's content policy at console.x.ai before building your integration. If you're building a user-facing product, add a moderation layer upstream so users get immediate feedback instead of waiting 20–30 seconds for a failed status.

AI-Generated Content Transparency: Label Before You Ship

Clearly indicate to your users when a video has been generated by AI. Many jurisdictions now require disclosure of AI-generated media. Action: Add a visible label (e.g., "Generated by AI") or a subtle watermark on every output video before serving it to end users.

Rate Limit Etiquette: Don't Bypass, Plan Around

The 1 request/second limit exists to protect API stability for all users. Don't bypass it through aggressive retry loops or parallel key rotation without a legitimate throughput need. Action: If you need more than 1 req/sec, contact xAI sales or switch to a third-party provider with higher limits rather than working around the restriction.

Data Handling: Know What Leaves Your Servers

Generated videos and source images are processed on xAI servers. Review xAI's data processing terms to understand how your inputs and outputs are handled. Action: Avoid sending sensitive, personally identifiable, or proprietary images to the API.

Once your production pipeline is running smoothly, you'll likely have a few practical questions. Here are the most common ones developers ask after their first integration.

FAQ

Can I use the Grok Imagine 1.5 API for free? No. The xAI API requires a paid account with a billing method attached. There is no free tier for API-based video generation. The free generations you see on grok.com/imagine are separate from the API and subject to strict daily limits.

Does the API support text-to-video (not image-to-video)? grok-imagine-video-1.5 is image-to-video only — it requires a source image. For text-to-video, you need to use the full grok-imagine-video suite model, which has different capabilities and pricing. If you don't have a source image, consider generating one first using the image generation API (POST /v1/images/generations) and then feeding it into the video model.

What's the difference between grok-imagine-video-1.5 and grok-imagine-video-1.5-preview? The -preview variant receives feature updates first (better motion handling, new capabilities) but is less stable. The GA model (grok-imagine-video-1.5) is production-grade and recommended for most use cases. The preview model may have breaking changes between versions.

How long does it take to generate a video via the API? A typical 6-second 720p video takes about 20–30 seconds from submission to completion. Factors that affect speed include: resolution (higher = slower), duration (longer = slower), and current API load.

Can I use the API with Postman or Insomnia? Yes. Set the Authorization header to Bearer YOUR_XAI_API_KEY and send a POST request to https://api.x.ai/v1/videos/generations with a JSON body matching the parameters above. The async workflow (submit → poll) works the same way.

What happens if my generated video fails content moderation? The API returns a failed status with an error indicating the content was rejected by the safety system. The prompt and image are not charged in this case, but repeated violations may result in account suspension.

Summary & Next Steps: Your First API Call in 3 Minutes

The Grok Imagine 1.5 API gives you programmatic access to one of the leading video generation models available today. The leap from clicking "Generate" on a web UI to orchestrating async API calls can feel like a different tool entirely — but once the submit → poll → retrieve pattern clicks, it unlocks automation and pipeline integration that no interface can match. Here's what to keep in mind:

• The API is async — submit a generation, poll or use a webhook to get the result
• Costs are per-second — $0.08 (480p), $0.14 (720p), or $0.25 (1080p) per second of video, plus $0.01 per input image
• Rate limit is 1 req/sec — queue submissions or use third-party providers for higher throughput
• Image-to-video only — you need a source image; no native text-to-video on this model
• Third-party options exist — Vercel, Cloudflare, AI/ML API, and OpenRouter all offer the model, each with different trade-offs

Your first step: Run the cURL command from the code examples section with your own API key and a publicly accessible image URL. Once you see "status": "queued" in the response, your setup is confirmed working. Keep polling the status endpoint every 5 seconds until the status changes to "done", then download your first generated video using the returned video_url. Start with a single 6-second 720p clip — it costs less than $1 and lets you validate the full submit → poll → download lifecycle before scaling up to production volumes.

If you hit rate limits, queue your requests or distribute across a third-party provider. If you need longer clips, generate multiple 15-second segments and stitch them together client-side. And if you're unsure which resolution to use, start with 720p — it gives the best quality-to-cost ratio for most use cases.