Grok Imagine API Guide: Image 2.0, Video, Pricing and Python Code

xAI’s Grok Imagine API now centres on grok-imagine-image-2.0 for images and grok-imagine-video-1.5 for video. On November 2, 2026, the older quality and pro image models were retired and moved to a cheaper setting.

This guide covers the models, the exact prices, working Python code and the new guidelines moderation array from October 27. Everything here is checked against xAI’s own docs.

What Changed in October and November 2026

Two recent updates matter if you use Grok Imagine or the Grok text API. Both come from xAI’s release notes.

November 2: image quality and pro models retired

Requests to grok-imagine-image-quality and grok-imagine-image-pro are now served by grok-imagine-image-2.0-low. That is grok-imagine-image-2.0 with quality set to low, at a lower per-image price.

• Your code: no request changes are needed. Old model names keep working.
• Your bill: the usage.cost_in_usd_ticks field in each response shows the new, lower price.
• gRPC users: responses through the xAI SDK report grok-imagine-image-2.0-low as the model.

Note: If you used the old pro model for its quality, test quality="medium" on grok-imagine-image-2.0. The automatic route uses low quality, which is cheaper but may look different.

October 27: custom moderation controls

You can now add a guidelines array to Chat Completions or Responses API requests. It tells Grok how to handle the nsfw, violence and profanity categories. There is a full section on it below.

Grok Imagine Models at a Glance

xAI’s models page lists two recommended media models, plus a lite video option and an older image model.

Since August 28, the quality setting on grok-imagine-image-2.0 also accepts auto. Auto currently means low for generation and medium for editing.

Grok Imagine API Pricing

These prices come from xAI’s pricing page. Images are billed per image and videos per second of output.

Quick cost examples

• 100 blog thumbnails at 1K low: 100 x $0.04 = $4.00.
• One 10 second 720p clip on video-1.5: 10 x $0.14 = $1.40.
• The same clip on video-1.5-lite: 10 x $0.03 = $0.30.

Warning: You are still charged if a request breaks xAI’s usage guidelines. In the Responses API, a violation caught before generation costs $0.05 per request. The Batch API supports images and video but gives no discount on them.

For Grok’s text model prices and the SuperGrok plans, see my Grok pricing guide.

Get an API Key and Install the SDK

1. Create an xAI account. Sign in to the xAI console and add credits or a payment method.
2. Create an API key. Generate a key in the console and copy it once. Never commit it to Git.
3. Store the key. Run export XAI_API_KEY="your_key" on macOS or Linux, or set it in your environment settings on Windows.
4. Install a client. Run pip install xai-sdk for the native SDK, or pip install openai to use the OpenAI-compatible endpoint.
5. Test a small request. Generate one 1K low quality image first, so a mistake costs only $0.04.

If you have never used the xAI API before, my Grok API Python tutorial walks through chat, streaming and tools with the same key.

Generate Images with Python

Option 1: the xAI Python SDK

import xai_sdk

client = xai_sdk.Client()  # reads XAI_API_KEY

response = client.image.sample(
    prompt="A cosy reading nook with a big window, warm morning light, watercolor style",
    model="grok-imagine-image-2.0",
    aspect_ratio="16:9",
    resolution="1k",
    quality="low",
)

print(response.url)

To get several images in one call, use client.image.sample_batch(prompt=..., model=..., n=4). The limit is 10 images per request.

Option 2: the OpenAI SDK

xAI’s endpoint is OpenAI-compatible, so you can reuse the openai package. Extra Grok settings go in extra_body.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key=os.environ["XAI_API_KEY"],
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A flat vector illustration of a rocket launching over a city skyline",
    n=2,
    extra_body={"aspect_ratio": "1:1", "resolution": "2k", "quality": "medium"},
)

for image in response.data:
    print(image.url)

Tip: Image URLs are temporary. Download each file straight away, or set response_format="b64_json" (OpenAI SDK) or image_format="base64" (xAI SDK) to get the image data directly.

Image Options: Quality, Size and Aspect Ratio

These are the main settings from xAI’s image generation docs:

• quality: low, medium or auto (default). Auto currently means low for generation. Only grok-imagine-image-2.0 supports it.
• resolution: 1k (default) or 2k.
• aspect_ratio: auto (default), 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 21:9, 5:2 and a few tall phone ratios.
• n: 1 to 10 images per request.
• response_format: url (default) or b64_json.

For long jobs, set deferred: true. You get a request_id back at once and poll GET /v1/images/{request_id}. Deferred results are kept for 24 hours.

Edit Images with the API

Editing uses the same image.sample call with an image_url. You can pass a public URL or a base64 data URI. Multi-image edits accept up to 5 source images.

import base64
import xai_sdk

client = xai_sdk.Client()

with open("photo.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.image.sample(
    prompt="Render this as a pencil sketch with detailed shading",
    model="grok-imagine-image-2.0",
    image_url=f"data:image/png;base64,{image_data}",
)

print(response.url)

Edits are billed for the input image ($0.01) and the generated output image. Only edit photos you own or have permission to use.

Generate Video with grok-imagine-video-1.5

Video is available through the API today. Requests are asynchronous: you start a job, then poll for the result. The xAI SDK polls for you.

import xai_sdk

client = xai_sdk.Client()

response = client.video.generate(
    prompt="A paper boat drifting down a rain-soaked street, cinematic",
    model="grok-imagine-video-1.5-lite",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)

Key video settings from xAI’s docs:

• duration: 1 to 15 seconds. The default is 8.
• resolution: 480p (default), 720p or 1080p. Reference-to-video on 1.5 tops out at 720p.
• aspect_ratio: 16:9 (default), 1:1, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9 or 5:2.
• Audio: on by default, with lip-synced speech. Pass generate_audio=False for a silent clip.
• Image-to-video: send an image with your prompt. The output keeps the image’s aspect ratio.

The REST flow uses POST /v1/videos/generations and then GET /v1/videos/{request_id} until the status is done. The response includes respect_moderation, which is false if the output was filtered.

Custom Moderation: the guidelines Array

Since October 27, 2026, text requests can carry a guidelines array. It is useful for family-friendly apps, schools and brand-safe chatbots.

How the array works

• type: always "policy".
• category: nsfw, violence or profanity.
• behavior: currently only decline.

With nsfw declined, Grok avoids sexual content but still answers educational and clinical questions. With violence declined, it can still discuss history and news without graphic detail. Categories you leave out keep the default behaviour.

Python example (OpenAI SDK)

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.x.ai/v1", api_key=os.environ["XAI_API_KEY"])

response = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Write a short story about a brave knight."}],
    extra_body={
        "guidelines": [
            {"type": "policy", "category": "violence", "behavior": "decline"},
            {"type": "policy", "category": "nsfw", "behavior": "decline"},
            {"type": "policy", "category": "profanity", "behavior": "decline"},
        ]
    },
)

print(response.choices[0].message.content)

Rules to remember

• Per request: guidelines apply only to the request that carries them, so send them every time. In the xAI SDK, chat.create stores them on the chat for you.
• Text only: xAI documents this for Chat Completions and the Responses API. It does not say it covers image or video calls.
• Not supported: multi-agent models such as grok-4.20-multi-agent and deferred completions. Some requests that set stop or n above 1 are also rejected.

Troubleshooting: Common Problems and Fixes

• Bill dropped after Nov 2: that is expected. Old quality and pro image requests now run at grok-imagine-image-2.0-low prices.
• Images look different than before: the auto route uses low quality. Switch to grok-imagine-image-2.0 with quality="medium".
• Image URL returns an error later: URLs are temporary. Download files at once or use base64 output.
• Image URL is missing: check respect_moderation. If it is false, moderation filtered the image, so rewrite the prompt.
• 422 error with guidelines: the category or behavior is unknown. Use only nsfw, violence or profanity, with decline.
• 400 error with guidelines: a category appears twice, type is not “policy”, or the model or option is not supported.
• Video job takes a long time: longer and higher resolution clips take more time. The Python SDK waits up to 10 minutes by default.

Frequently Asked Questions

What is the best Grok Imagine model for images?

Use grok-imagine-image-2.0. It is xAI’s recommended image model, with 1K and 2K output, low or medium quality and editing support.

How much does the Grok Imagine API cost per image?

From $0.04 for a 1K low quality image up to $0.08 for a 2K medium image on grok-imagine-image-2.0. The older grok-imagine-image costs $0.02 per image.

What happened to grok-imagine-image-pro?

Since November 2, 2026, requests to grok-imagine-image-pro and grok-imagine-image-quality are served by grok-imagine-image-2.0-low. They keep working with no code change, at a lower price.

Does the Grok Imagine API support video?

Yes. grok-imagine-video-1.5 and grok-imagine-video-1.5-lite make clips of 1 to 15 seconds at up to 1080p, from $0.02 per second on lite.

Can I use the OpenAI Python SDK with Grok Imagine?

Yes. Set base_url to https://api.x.ai/v1, use your xAI key, and pass Grok-only settings like aspect_ratio in extra_body.

What is the guidelines array in the xAI API?

It is a list of policy rules you add to a text request, such as declining violence or profanity. It was added on October 27, 2026 for Chat Completions and the Responses API.

Am I charged if my image prompt is blocked?

Yes. xAI still charges for generation when a request violates its usage guidelines, and a Responses API violation caught before generation costs $0.05.

Comparing Grok with other assistants? Read my ChatGPT vs Claude vs Gemini vs Grok comparison.

Sources

• xAI Docs: Release notes
• xAI Docs: Pricing
• xAI Docs: Models
• xAI Docs: Imagine API guide
• xAI Docs: Image generation
• xAI Docs: Video generation
• xAI Docs: Custom moderation controls
• Releasebot: xAI updates