Grok Imagine API: Integration Guide, Pricing & Code

The Grok Imagine API is xAI’s endpoint for generating images and video from code — it is not the Grok chatbot, and it has nothing to do with the same-named crypto token that shows up in search results. If you have decided to build with Grok Imagine and now need to wire it into a product or script, the one thing to internalize up front is this: Imagine exposes two request patterns. Image generation and editing are synchronous — you POST a prompt and get an image URL back in the same response. Video is asynchronous — you POST a prompt, get a request_id, and poll a second endpoint until the video is ready. Everything else is just parameters.

This guide walks the whole path from a single API key to a finished image and a finished video, using only xAI’s first-party documentation (as of July 2026). It covers authentication, the image endpoint, the asynchronous video endpoint and its polling loop, image-to-video, and rate limits. Pricing has its own dedicated breakdown and alternatives have theirs, so both are linked rather than repeated here — this page is about how you call it.

What the Grok Imagine API does

Grok Imagine is xAI’s media-generation product, and its API surface is small and predictable. There are two families of models:

Model ID	Task	Pattern
grok-imagine-image	Text-to-image (standard)	Synchronous
grok-imagine-image-quality	Text-to-image (higher quality, 2K)	Synchronous
grok-imagine-video	Text-to-video	Asynchronous
grok-imagine-video-1.5	Image-to-video, up to 1080p	Asynchronous

On top of plain generation, the API also supports image editing (modify an image with up to three reference images), image-to-video (animate a still), and video workflows like reference-to-video and extending an existing clip. The consumer-facing capability ceiling is up to 2K resolution for images and 15-second videos.

One clarification that saves debugging time: these are media endpoints, not the Grok chat model. If you have used grok-4.5 through /v1/responses, Imagine is a different surface — /v1/images and /v1/videos — even though it lives under the same base URL and uses the same key.

Grok Imagine API pricing at a glance

The short version, so you can size a bill before writing any code: the standard image model is $0.02 per image (at both 1K and 2K) and standard video starts at $0.05 per second at 480p, as of July 2026, with higher tiers for the quality image model and the 1.5 video model. Two constraints matter for architecture: image and video are billed at standard rates even inside the Batch API, and Priority Processing is not offered — so there is no volume-discount lever to pull. For the full per-tier ladder (every model, every resolution), see the full xAI pricing on Modellix’s provider page; this page keeps pricing to a summary on purpose.

Setting up: your API key and base URL

Everything authenticates the same way, so this setup applies to every call below.

1. Create a key. Generate one on the API Keys page in the xAI console, then export it.

   export XAI_API_KEY="your_api_key"

2. Point at the base URL. All Imagine requests go to https://api.x.ai/v1, with your key in a Bearer header:

   Authorization: Bearer ***

3. Pick an SDK, or skip it. You can install xAI’s native SDK, or reuse the OpenAI SDK since the API is OpenAI-compatible — just re-point the base URL:

   pip install xai-sdk      # native
   pip install openai       # OpenAI-compatible path

   from openai import OpenAI
   
   client = OpenAI(
       api_key="<YOUR_XAI_API_KEY_HERE>",
       base_url="https://api.x.ai/v1",
   )

Because raw HTTP is the common denominator across languages, the examples below use curl (based on xAI’s docs) and Python requests, which mirror the wire format exactly.

Generating an image with the Grok Imagine API (synchronous)

Image generation is a single synchronous call to POST /v1/images/generations. You send a model and a prompt; the response comes back with the image URL.

The request body accepts:

Parameter	Type	Notes
model	string	Required, e.g. "grok-imagine-image-quality"
prompt	string	Required, the text description
n	integer	Optional, number of images (batch)
aspect_ratio	string	Optional, e.g. "16:9", "1:1", "auto"
resolution	string	Optional, "1k" or "2k"
response_format	string	Optional, "b64_json" to get base64 instead of a URL

The minimal call, based on the docs:

curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "A collage of London landmarks in a stenciled street-art style"
  }'

The same request in Python:

import os, requests

resp = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    json={
        "model": "grok-imagine-image-quality",
        "prompt": "A collage of London landmarks in a stenciled street-art style",
        "resolution": "2k",
    },
)
print(resp.json()["data"][0]["url"])

By default the image comes back as a URL (data[0].url); pass response_format: "b64_json" and you get data[0].b64_json instead. To edit an existing image rather than generate from scratch, use POST /v1/images/edits, which accepts up to three reference images for multi-image editing. Both are synchronous — no polling.

Generating a video (asynchronous, with polling)

Video is where the pattern changes, and it is the single most common integration mistake: you cannot expect the video in the first response. Instead, POST /v1/videos/generations returns a request_id, and you poll GET /v1/videos/{request_id} until the status field flips from pending to done (or failed / expired).

xAI’s own developer docs, captured July 26, 2026 — video generation is a two-step Start/Poll process: the POST returns a request_id, then you GET /v1/videos/{request_id} until the video is ready. This is the async contract the whole video path is built on.

The generation request accepts model, prompt, an optional duration (1–15 seconds), an aspect_ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3), and a resolution (480p default, 720p, or 1080p).

The two steps in curl, based on the docs:

REQUEST_ID=$(curl -s -X POST https://api.x.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{"model":"grok-imagine-video","prompt":"...","duration":10}' \
  | jq -r '.request_id')

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

When the job finishes, the poll returns the video URL:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/.../video.mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "model": "grok-imagine-video"
}

A complete Python polling loop looks like this:

import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"}

start = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={"model": "grok-imagine-video", "prompt": "...", "duration": 10},
)
request_id = start.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/{request_id}", headers=headers
    ).json()
    if result["status"] in ("done", "failed", "expired"):
        break
    time.sleep(3)

print(result["video"]["url"])

If you use xAI’s SDK, the generate() and extend() methods hide this loop entirely — they submit the request, poll, and return the completed video. Drop to start() and get() when you want to manage polling yourself.

Image-to-video, editing, and reference inputs

Animating a still image runs through the same POST /v1/videos/generations endpoint and the same polling loop; the difference is that you supply an input image, and you choose a model that supports it (grok-imagine-video-1.5 also unlocks 1080p output). The API accepts an input image in three forms: a public URL, a base64-encoded data URI (e.g. data:image/jpeg;base64,...), or a file_id from the Files API.

If you are on the Vercel AI SDK, the prompt parameter takes an object with image and text fields, where the image can be a URL, a base64 string, a Uint8Array, an ArrayBuffer, or a Buffer. Because reference-to-video and video extension reuse the same asynchronous contract, once you have the polling loop above, adding these workflows is a matter of swapping the model and payload — not learning a new endpoint.

Rate limits and error handling

Imagine models are throttled by requests per second, not tokens per minute. As of July 2026, the published limits are:

Model	Limit
grok-imagine-image	5 RPS
grok-imagine-image-quality	5 RPS
grok-imagine-video	10 RPS
grok-imagine-video-1.5	10 RPS

xAI’s rate-limit docs, captured July 26, 2026 — Imagine image models are capped at 5 requests per second and video models at 10, across all tiers, confirming the throttle is RPS-based rather than token-based.

Exceed them and you get an HTTP 429; the recommended response is to catch the rate-limit error and back off exponentially before retrying:

import time, requests

def with_backoff(call, retries=5):
    for attempt in range(retries):
        resp = call()
        if resp.status_code != 429:
            return resp
        time.sleep(2 ** attempt)   # 1s, 2s, 4s, 8s, ...
    return resp

One important note if you are planning for scale: rate-limit tier upgrades apply to text and embedding models, but increases to Imagine limits are handled by contacting sales@x.ai, not through automatic tier bumps. Combined with the absence of Batch or Priority discounts on image and video, that means capacity and cost for high-volume Imagine workloads are worth confirming with xAI before you commit.

Access Grok Imagine (and other models) through one API key

If Grok Imagine is one of several models you are calling, you may not want a separate integration for each provider. Modellix is an aggregation layer that carries the full Grok Imagine family (ten Imagine models in all — this guide details the four workhorse IDs above) behind one API key, using a single asynchronous contract: POST /api/v1/xai/<model>/async returns a task_id, and GET /api/v1/tasks/{task_id} retrieves the result. The same key and the same submit-poll lifecycle reach image and video models from other providers too, and every call is logged with its per-request cost, which makes running the same prompt across models an apples-to-apples comparison.

To be straight about the trade-off: this is not a claim that routing Grok Imagine through Modellix is cheaper. Its per-tier markup means the direct xAI API is the lower-cost path if Grok is all you need — the standard image tier is roughly $0.023 versus xAI’s $0.02, and standard video roughly $0.0575 versus $0.05. The aggregator earns its keep only when you want one key across many image and video models plus per-call cost logs, not when you are optimizing a single-provider bill. If you are still deciding which model to build on at all, the honest Grok Imagine alternatives comparison covers the strongest image and video substitutes.

Frequently Asked Questions about the Grok Imagine API

How do I get a Grok Imagine API key? Create a key on the API Keys page in the xAI console, then set it as the XAI_API_KEY environment variable. The same key works for both image and video endpoints.

What is the Grok Imagine API endpoint? There are two: images go to POST https://api.x.ai/v1/images/generations and videos to POST https://api.x.ai/v1/videos/generations, both under the base URL https://api.x.ai/v1. Video results are retrieved from GET /v1/videos/{request_id}.

Is the image API synchronous and the video API asynchronous? Yes. Image generation and editing return the result in the same response. Video generation returns a request_id that you poll until status is done. Building around that difference is the main thing to get right.

How much does the Grok Imagine API cost? It is usage-based — priced per image and per second of video, with higher tiers for the quality and 1.5 models, and no Batch or Priority discount. The full per-resolution ladder is on the Modellix xAI provider page.

Can I generate video from an image? Yes. Image-to-video uses the same /v1/videos/generations endpoint and polling loop; you pass the input image as a public URL, a base64 data URI, or a Files API file_id, and use a model that supports it (grok-imagine-video-1.5 also reaches 1080p).

What are the rate limits? Image models are capped at 5 requests per second and video models at 10, as of July 2026. Exceeding them returns HTTP 429; retry with exponential backoff, and contact sales@x.ai for higher Imagine limits.

Can I use the OpenAI SDK with it? Yes. The API is OpenAI-compatible, so you can point the OpenAI client at https://api.x.ai/v1 and pass your XAI_API_KEY, or use xAI’s native xai-sdk.

Is the Grok Imagine API the same as the crypto token or the Grok chatbot? No. The crypto token that shares the name is unrelated to xAI’s product. And Grok Imagine is a media-generation API on /v1/images and /v1/videos — separate from the grok-4.5 chat model on /v1/responses.

---

Endpoint behavior, model IDs, rate limits, and pricing reflect xAI’s public documentation as of July 2026 and change frequently. Validate against the live docs before shipping. Access image and video models, including the leading Chinese models, through a single API key at modellix.ai.