Model Capabilities

Image Generation

Generate images from text prompts with Grok Imagine models. The API supports batch generation of multiple images, and control over aspect ratio, resolution, and quality.

Quick Start

Generate an image with a single API call:

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "A collage of London landmarks in a stenciled street‑art style",
});

console.log(image.base64);

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A collage of London landmarks in a stenciled street‑art style",
)

print(response.data[0].url)

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

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.XAI_API_KEY,
    baseURL: 'https://api.x.ai/v1',
});

const response = await client.images.generate({
    model: "grok-imagine-image-2.0",
    prompt: "A collage of London landmarks in a stenciled street‑art style",
});

console.log(response.data[0].url);

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="A collage of London landmarks in a stenciled street‑art style",
    model="grok-imagine-image-2.0",
)

print(response.url)

Images are returned as URLs by default. URLs are temporary, so download or process promptly. You can also request base64 output for embedding images directly.

Configuration

Multiple Images

Generate multiple images in a single request with the n parameter (1–10). On the REST API and OpenAI-compatible SDKs, n is optional and defaults to 1. The xAI Python SDK uses sample() for a single image and sample_batch(n=...) for more than one — n is required on sample_batch().

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

const { images } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "A futuristic city skyline at night",
    n: 4,
});

images.forEach((image, i) => {
    console.log(`Variation ${i + 1}: ${image.base64.slice(0, 50)}...`);
});

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A futuristic city skyline at night",
    n=4,
)

for i, image in enumerate(response.data):
    print(f"Variation {i + 1}: {image.url}")

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.XAI_API_KEY,
    baseURL: "https://api.x.ai/v1",
});

const response = await client.images.generate({
    model: "grok-imagine-image-2.0",
    prompt: "A futuristic city skyline at night",
    n: 4,
});

response.data.forEach((image, i) => {
    console.log(`Variation ${i + 1}: ${image.url}`);
});

curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A futuristic city skyline at night",
    "n": 4
  }'

import xai_sdk

client = xai_sdk.Client()

responses = client.image.sample_batch(
    prompt="A futuristic city skyline at night",
    model="grok-imagine-image-2.0",
    n=4,
)

for i, image in enumerate(responses):
    print(f"Variation {i + 1}: {image.url}")

Aspect Ratio

Control image dimensions with the aspect_ratio parameter. When omitted, the default is auto, which lets the model pick the best ratio for the prompt.

Ratio	Use case
`1:1`	Social media, thumbnails
`16:9` / `9:16`	Widescreen, mobile, stories
`4:3` / `3:4`	Presentations, portraits
`3:2` / `2:3`	Photography
`2:1` / `1:2`	Banners, headers
`19.5:9` / `9:19.5`	Modern smartphone displays (iPhone)
`20:9` / `9:20`	Modern smartphone displays (Android)
`21:9`	Cinematic widescreen
`5:2`	Wide banners
`auto`	Model auto-selects the best ratio for the prompt

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "Mountain landscape at sunrise",
    aspectRatio: "16:9",
});

console.log(image.base64);

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="Mountain landscape at sunrise",
    extra_body={"aspect_ratio": "16:9"},
)

print(response.data[0].url)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.XAI_API_KEY,
    baseURL: "https://api.x.ai/v1",
});

const response = await client.images.generate({
    model: "grok-imagine-image-2.0",
    prompt: "Mountain landscape at sunrise",

    aspect_ratio: "16:9",
});

console.log(response.data[0].url);

curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Mountain landscape at sunrise",
    "aspect_ratio": "16:9"
  }'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="Mountain landscape at sunrise",
    model="grok-imagine-image-2.0",
    aspect_ratio="16:9",
)

print(response.url)

Resolution

You can specify different resolutions of the output image with the resolution parameter. Currently supported image resolutions are:

1k (default when omitted)
2k

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "An astronaut performing EVA in LEO.",
    providerOptions: {
        xai: { resolution: "2k" },
    },
});

console.log(image.base64);

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="An astronaut performing EVA in LEO.",
    extra_body={"resolution": "2k"},
)

print(response.data[0].url)

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.XAI_API_KEY,
    baseURL: "https://api.x.ai/v1",
});

const response = await client.images.generate({
    model: "grok-imagine-image-2.0",
    prompt: "An astronaut performing EVA in LEO.",

    resolution: "2k",
});

console.log(response.data[0].url);

curl -X POST https://api.x.ai/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $XAI_API_KEY" \
-d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "An astronaut performing EVA in LEO.",
    "resolution": "2k"
}'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="An astronaut performing EVA in LEO.",
    model="grok-imagine-image-2.0",
    resolution="2k"
)

print(response.url)

Quality

Control generation quality with the optional quality parameter. Allowed values are low, medium, and auto. When omitted, the default is auto, which lets the service choose the quality for each request. Auto currently uses low for image generation and medium for image editing. Images are billed at the quality they are served at (see Pricing). Pass low or medium to pin a specific quality. The parameter is only supported for grok-imagine-image-2.0.

curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A watercolor painting of a lighthouse at dawn",
    "quality": "low"
  }'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="A watercolor painting of a lighthouse at dawn",
    model="grok-imagine-image-2.0",
    quality="low",
)

print(response.url)

Base64 Output

Control the output format with the response_format parameter. When omitted, the default is url, which returns temporary hosted URLs. For embedding images directly without downloading, request base64:

import { xai } from "@ai-sdk/xai";
import { generateImage } from "ai";
import fs from "fs";

const { image } = await generateImage({
    model: xai.image("grok-imagine-image-2.0"),
    prompt: "A serene Japanese garden",
});

// Save to file (AI SDK returns base64 by default)
const imageBuffer = Buffer.from(image.base64, "base64");
fs.writeFileSync("garden.jpg", imageBuffer);

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A serene Japanese garden",
    response_format="b64_json",
)

# Save to file
image_bytes = base64.b64decode(response.data[0].b64_json)
with open("garden.jpg", "wb") as f:
    f.write(image_bytes)

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
    apiKey: process.env.XAI_API_KEY,
    baseURL: "https://api.x.ai/v1",
});

const response = await client.images.generate({
    model: "grok-imagine-image-2.0",
    prompt: "A serene Japanese garden",
    response_format: "b64_json",
});

// Save to file
const imageBuffer = Buffer.from(response.data[0].b64_json, "base64");
fs.writeFileSync("garden.jpg", imageBuffer);

curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A serene Japanese garden",
    "response_format": "b64_json"
  }'

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    prompt="A serene Japanese garden",
    model="grok-imagine-image-2.0",
    image_format="base64",
)

# Save to file
with open("garden.jpg", "wb") as f:
    f.write(response.image)

Deferred Generation

Image generation normally completes within the request. For long-running batches, or to avoid holding a connection open, set deferred: true on /v1/images/generations or /v1/images/edits. The request returns a request_id immediately; poll GET /v1/images/{request_id} for the result. Deferred requests support response_format: "url" only (the default). Results are stored alongside deferred chat completions and retained for 24 hours.

The poll response carries a status:

pending (HTTP 202): still generating
done (HTTP 200): data and usage are populated, in the same shape as a synchronous response
failed (HTTP 200): error holds a code and message

import os
import time
import requests

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json",
}

# Step 1: Start generation
response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image-2.0",
        "prompt": "A serene Japanese garden",
        "deferred": True,
    },
)
request_id = response.json()["request_id"]

# Step 2: Poll for the result
while True:
    result = requests.get(
        f"https://api.x.ai/v1/images/{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()

    if data["status"] == "done":
        print(f"Image URL: {data['data'][0]['url']}")
        break
    elif data["status"] == "failed":
        print(f"Generation failed: {data['error']['message']}")
        break
    else:
        print("Still processing...")
        time.sleep(5)

# Step 1: Start generation
curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A serene Japanese garden",
    "deferred": true
  }'
# => {"request_id": "..."}

# Step 2: Poll for the result
curl https://api.x.ai/v1/images/<request_id> \
  -H "Authorization: Bearer $XAI_API_KEY"
# => 202 {"request_id": "...", "status": "pending"}
# => 200 {"request_id": "...", "status": "done", "data": [{"url": "...", "mime_type": "image/jpeg"}], "usage": {...}}

You can also register a webhook for the image.generation.completed, image.generation.failed, image.edit.completed and image.edit.failed events instead of polling.

Response Details

The xAI SDK exposes additional metadata on the response object beyond the image URL or base64 data.

Moderation — Check whether the generated image passed content moderation:

if response.respect_moderation:
    print(response.url)
else:
    print("Image filtered by moderation")

Model — Get the actual model used (resolving any aliases):

print(f"Model: {response.model}")

Concurrent Requests

When you need to generate multiple images with different prompts, such as generating unrelated images in parallel, use AsyncClient with asyncio.gather to fire requests concurrently. This is significantly faster than issuing them one at a time.

[!TIP]

If you want multiple variations from the same prompt, use sample_batch() with the n parameter` instead. That generates all images in a single request and is the most efficient approach for same-prompt generation.

import asyncio
import xai_sdk

async def generate_concurrently():
    client = xai_sdk.AsyncClient()

    # Each request uses a different prompt
    prompts = [
        "A futuristic city skyline at sunset",
        "A serene Japanese garden in winter",
        "An astronaut floating above Earth",
        "A medieval castle on a misty mountain",
    ]

    # Fire all requests concurrently
    tasks = [
        client.image.sample(
            prompt=prompt,
            model="grok-imagine-image-2.0",
        )
        for prompt in prompts
    ]

    results = await asyncio.gather(*tasks)

    for prompt, result in zip(prompts, results):
        print(f"{prompt}: {result.url}")

asyncio.run(generate_concurrently())

Models — Available image models
Image Editing — Edit images with natural language
Image Generation Tool — Let Grok generate and edit images inside a conversation
Video Generation — Generate videos from text prompts
API Reference — Full endpoint documentation
Imagine API Landing Page — Showcase of the Imagine API in action

model-capabilities/images/generation.md +199 −127

8 8

9Generate an image with a single API call:9Generate an image with a single API call:

10 10

~~11```python customLanguage="pythonXAI"~~11```javascript customLanguage="javascriptAISDK"

~~12import xai_sdk~~12import { xai } from "@ai-sdk/xai";

13 13import { generateImage } from "ai";

~~14client = xai_sdk.Client()~~

~~16response = client.image.sample(~~

~~17 prompt="A collage of London landmarks in a stenciled street‑art style",~~

~~18 model="grok-imagine-image-2.0",~~

~~19)~~

20 14

~~21print(response.url)~~15const { image } = await generateImage({

~~22```~~16 model: xai.image("grok-imagine-image-2.0"),

17 prompt: "A collage of London landmarks in a stenciled street‑art style",

18});

23 19

~~24```bash~~20console.log(image.base64);

~~25curl -X POST https://api.x.ai/v1/images/generations \~~

~~26 -H "Content-Type: application/json" \~~

~~27 -H "Authorization: Bearer $XAI_API_KEY" \~~

~~28 -d '{~~

~~29 "model": "grok-imagine-image-2.0",~~

~~30 "prompt": "A collage of London landmarks in a stenciled street‑art style"~~

~~31 }'~~

32```21```

33 22

34```python customLanguage="pythonOpenAISDK"23```python customLanguage="pythonOpenAISDK"

47print(response.data[0].url)36print(response.data[0].url)

48```37```

49 38

39```bash

40curl -X POST https://api.x.ai/v1/images/generations \

41 -H "Content-Type: application/json" \

42 -H "Authorization: Bearer $XAI_API_KEY" \

43 -d '{

44 "model": "grok-imagine-image-2.0",

45 "prompt": "A collage of London landmarks in a stenciled street‑art style"

46 }'

47```

50```javascript customLanguage="javascriptOpenAISDK"49```javascript customLanguage="javascriptOpenAISDK"

51import OpenAI from "openai";50import OpenAI from "openai";

52 51

63console.log(response.data[0].url);62console.log(response.data[0].url);

64```63```

65 64

~~66```javascript customLanguage="javascriptAISDK"~~65```python customLanguage="pythonXAI"

~~67import { xai } from "@ai-sdk/xai";~~66import xai_sdk

~~68import { generateImage } from "ai";~~

69 67

~~70const { image } = await generateImage({~~68client = xai_sdk.Client()

~~71 model: xai.image("grok-imagine-image-2.0"),~~

~~72 prompt: "A collage of London landmarks in a stenciled street‑art style",~~

~~73});~~

74 69

~~75console.log(image.base64);~~70response = client.image.sample(

71 prompt="A collage of London landmarks in a stenciled street‑art style",

72 model="grok-imagine-image-2.0",

73)

75print(response.url)

76```76```

77 77

78Images are returned as URLs by default. URLs are temporary, so download or process promptly. You can also request [base64 output](#base64-output) for embedding images directly.78Images are returned as URLs by default. URLs are temporary, so download or process promptly. You can also request [base64 output](#base64-output) for embedding images directly.

83 83

84Generate multiple images in a single request with the `n` parameter (`1`–`10`). On the REST API and OpenAI-compatible SDKs, `n` is optional and defaults to `1`. The xAI Python SDK uses `sample()` for a single image and `sample_batch(n=...)` for more than one — `n` is required on `sample_batch()`.84Generate multiple images in a single request with the `n` parameter (`1`–`10`). On the REST API and OpenAI-compatible SDKs, `n` is optional and defaults to `1`. The xAI Python SDK uses `sample()` for a single image and `sample_batch(n=...)` for more than one — `n` is required on `sample_batch()`.

85 85

~~86```python customLanguage="pythonXAI"~~86```javascript customLanguage="javascriptAISDK"

~~87import xai_sdk~~87import { xai } from "@ai-sdk/xai";

88import { generateImage } from "ai";

88 89

~~89client = xai_sdk.Client()~~90const { images } = await generateImage({

91 model: xai.image("grok-imagine-image-2.0"),

92 prompt: "A futuristic city skyline at night",

93 n: 4,

94});

90 95

~~91responses = client.image.sample_batch(~~96images.forEach((image, i) => {

~~92 prompt="A futuristic city skyline at night",~~97 console.log(`Variation ${i + 1}: ${image.base64.slice(0, 50)}...`);

~~93 model="grok-imagine-image-2.0",~~98});

~~94 n=4,~~

~~95)~~

96 99

~~97for i, image in enumerate(responses):~~

~~98 print(f"Variation {i + 1}: {image.url}")~~

99```100```

100 101

101```python customLanguage="pythonOpenAISDK"102```python customLanguage="pythonOpenAISDK"

136 137

137```138```

138 139

139```javascript customLanguage="javascriptAISDK"

140import { xai } from "@ai-sdk/xai";

141import { generateImage } from "ai";

~~142~~

143const { images } = await generateImage({

144 model: xai.image("grok-imagine-image-2.0"),

145 prompt: "A futuristic city skyline at night",

146 n: 4,

147});

~~148~~

149images.forEach((image, i) => {

150 console.log(`Variation ${i + 1}: ${image.base64.slice(0, 50)}...`);

151});

~~152~~

153```

~~154~~

155```bash140```bash

156curl -X POST https://api.x.ai/v1/images/generations \141curl -X POST https://api.x.ai/v1/images/generations \

157 -H "Content-Type: application/json" \142 -H "Content-Type: application/json" \

163 }'148 }'

164```149```

165 150

151```python customLanguage="pythonXAI"

152import xai_sdk

153

154client = xai_sdk.Client()

155

156responses = client.image.sample_batch(

157 prompt="A futuristic city skyline at night",

158 model="grok-imagine-image-2.0",

159 n=4,

160)

161

162for i, image in enumerate(responses):

163 print(f"Variation {i + 1}: {image.url}")

164```

165

166### Aspect Ratio166### Aspect Ratio

167 167

168Control image dimensions with the `aspect_ratio` parameter. When omitted, the default is `auto`, which lets the model pick the best ratio for the prompt.168Control image dimensions with the `aspect_ratio` parameter. When omitted, the default is `auto`, which lets the model pick the best ratio for the prompt.

180| `5:2` | Wide banners |180| `5:2` | Wide banners |

182 182

183```python customLanguage="pythonXAI"183```javascript customLanguage="javascriptAISDK"

184import xai_sdk184import { xai } from "@ai-sdk/xai";

~~185~~ 185import { generateImage } from "ai";

186client = xai_sdk.Client()

187 186

188response = client.image.sample(187const { image } = await generateImage({

189 prompt="Mountain landscape at sunrise",188 model: xai.image("grok-imagine-image-2.0"),

190 model="grok-imagine-image-2.0",189 prompt: "Mountain landscape at sunrise",

191 aspect_ratio="16:9",190 aspectRatio: "16:9",

192)191});

193 192

194print(response.url)193console.log(image.base64);

195```194```

196 195

197```python customLanguage="pythonOpenAISDK"196```python customLanguage="pythonOpenAISDK"

229console.log(response.data[0].url);228console.log(response.data[0].url);

230```229```

231 230

232```javascript customLanguage="javascriptAISDK"

233import { xai } from "@ai-sdk/xai";

234import { generateImage } from "ai";

~~235~~

236const { image } = await generateImage({

237 model: xai.image("grok-imagine-image-2.0"),

238 prompt: "Mountain landscape at sunrise",

239 aspectRatio: "16:9",

240});

~~241~~

242console.log(image.base64);

243```

~~244~~

245```bash231```bash

246curl -X POST https://api.x.ai/v1/images/generations \232curl -X POST https://api.x.ai/v1/images/generations \

247 -H "Content-Type: application/json" \233 -H "Content-Type: application/json" \

253 }'239 }'

254```240```

255 241

256### Resolution

~~257~~

258You can specify different resolutions of the output image with the `resolution` parameter. Currently supported image resolutions are:

~~259~~

260* `1k` (default when omitted)

261* `2k`

~~262~~

263```python customLanguage="pythonXAI"242```python customLanguage="pythonXAI"

264import xai_sdk243import xai_sdk

265 244

266client = xai_sdk.Client()245client = xai_sdk.Client()

267 246

268response = client.image.sample(247response = client.image.sample(

269 prompt="An astronaut performing EVA in LEO.",248 prompt="Mountain landscape at sunrise",

270 model="grok-imagine-image-2.0",249 model="grok-imagine-image-2.0",

271 resolution="2k"250 aspect_ratio="16:9",

272)251)

273 252

274print(response.url)253print(response.url)

275```254```

276 255

256### Resolution

257

258You can specify different resolutions of the output image with the `resolution` parameter. Currently supported image resolutions are:

259

260* `1k` (default when omitted)

261* `2k`

262

263```javascript customLanguage="javascriptAISDK"

264import { xai } from "@ai-sdk/xai";

265import { generateImage } from "ai";

266

267const { image } = await generateImage({

268 model: xai.image("grok-imagine-image-2.0"),

269 prompt: "An astronaut performing EVA in LEO.",

270 providerOptions: {

271 xai: { resolution: "2k" },

272 },

273});

274

275console.log(image.base64);

276```

277

277```python customLanguage="pythonOpenAISDK"278```python customLanguage="pythonOpenAISDK"

278from openai import OpenAI279from openai import OpenAI

279 280

309console.log(response.data[0].url);310console.log(response.data[0].url);

310```311```

311 312

312```javascript customLanguage="javascriptAISDK"

313import { xai } from "@ai-sdk/xai";

314import { generateImage } from "ai";

~~315~~

316const { image } = await generateImage({

317 model: xai.image("grok-imagine-image-2.0"),

318 prompt: "An astronaut performing EVA in LEO.",

319 providerOptions: {

320 xai: { resolution: "2k" },

321 },

322});

~~323~~

324console.log(image.base64);

325```

~~326~~

327```bash313```bash

328curl -X POST https://api.x.ai/v1/images/generations \314curl -X POST https://api.x.ai/v1/images/generations \

329-H "Content-Type: application/json" \315-H "Content-Type: application/json" \

335}'321}'

336```322```

337 323

338### Quality

~~339~~

340Control generation quality with the optional `quality` parameter. Allowed values are `low`, `medium`, and `auto`. When omitted, the default is `auto`, which lets the service choose the quality for each request. Auto currently uses `low` for image generation and `medium` for [image editing](/developers/model-capabilities/images/editing). Images are billed at the quality they are served at (see [Pricing](/developers/pricing)). Pass `low` or `medium` to pin a specific quality. The parameter is only supported for `grok-imagine-image-2.0`.

~~341~~

342```python customLanguage="pythonXAI"324```python customLanguage="pythonXAI"

343import xai_sdk325import xai_sdk

344 326

345client = xai_sdk.Client()327client = xai_sdk.Client()

346 328

347response = client.image.sample(329response = client.image.sample(

348 prompt="A watercolor painting of a lighthouse at dawn",330 prompt="An astronaut performing EVA in LEO.",

349 model="grok-imagine-image-2.0",331 model="grok-imagine-image-2.0",

350 quality="low",332 resolution="2k"

351)333)

352 334

353print(response.url)335print(response.url)

354```336```

355 337

338### Quality

339

341

356```bash342```bash

357curl -X POST https://api.x.ai/v1/images/generations \343curl -X POST https://api.x.ai/v1/images/generations \

358 -H "Content-Type: application/json" \344 -H "Content-Type: application/json" \

364 }'350 }'

365```351```

366 352

367### Base64 Output

~~368~~

369Control the output format with the `response_format` parameter. When omitted, the default is `url`, which returns temporary hosted URLs. For embedding images directly without downloading, request base64:

~~370~~

371```python customLanguage="pythonXAI"353```python customLanguage="pythonXAI"

372import xai_sdk354import xai_sdk

373 355

374client = xai_sdk.Client()356client = xai_sdk.Client()

375 357

376response = client.image.sample(358response = client.image.sample(

377 prompt="A serene Japanese garden",359 prompt="A watercolor painting of a lighthouse at dawn",

378 model="grok-imagine-image-2.0",360 model="grok-imagine-image-2.0",

379 image_format="base64",361 quality="low",

380)362)

381 363

382# Save to file364print(response.url)

383with open("garden.jpg", "wb") as f:365```

384 f.write(response.image)366

367### Base64 Output

368

370

371```javascript customLanguage="javascriptAISDK"

372import { xai } from "@ai-sdk/xai";

373import { generateImage } from "ai";

374import fs from "fs";

375

376const { image } = await generateImage({

377 model: xai.image("grok-imagine-image-2.0"),

378 prompt: "A serene Japanese garden",

379});

380

381// Save to file (AI SDK returns base64 by default)

382const imageBuffer = Buffer.from(image.base64, "base64");

383fs.writeFileSync("garden.jpg", imageBuffer);

385```384```

386 385

387```python customLanguage="pythonOpenAISDK"386```python customLanguage="pythonOpenAISDK"

425fs.writeFileSync("garden.jpg", imageBuffer);424fs.writeFileSync("garden.jpg", imageBuffer);

426```425```

427 426

428```javascript customLanguage="javascriptAISDK"427```bash

429import { xai } from "@ai-sdk/xai";428curl -X POST https://api.x.ai/v1/images/generations \

430import { generateImage } from "ai";429 -H "Content-Type: application/json" \

431import fs from "fs";430 -H "Authorization: Bearer $XAI_API_KEY" \

431 -d '{

432 "model": "grok-imagine-image-2.0",

433 "prompt": "A serene Japanese garden",

434 "response_format": "b64_json"

435 }'

436```

432 437

433const { image } = await generateImage({438```python customLanguage="pythonXAI"

434 model: xai.image("grok-imagine-image-2.0"),439import xai_sdk

435 prompt: "A serene Japanese garden",

436});

437 440

438// Save to file (AI SDK returns base64 by default)441client = xai_sdk.Client()

439const imageBuffer = Buffer.from(image.base64, "base64");442

440fs.writeFileSync("garden.jpg", imageBuffer);443response = client.image.sample(

444 prompt="A serene Japanese garden",

445 model="grok-imagine-image-2.0",

446 image_format="base64",

447)

448

449# Save to file

450with open("garden.jpg", "wb") as f:

451 f.write(response.image)

452```

453

454### Deferred Generation

455

456Image generation normally completes within the request. For long-running batches, or to avoid holding a connection open, set `deferred: true` on `/v1/images/generations` or `/v1/images/edits`. The request returns a `request_id` immediately; poll `GET /v1/images/{request_id}` for the result. Deferred requests support `response_format: "url"` only (the default). Results are stored alongside [deferred chat completions](/developers/advanced-api-usage/deferred-chat-completions) and retained for 24 hours.

457

458The poll response carries a `status`:

459

460* `pending` (HTTP `202`): still generating

461* `done` (HTTP `200`): `data` and `usage` are populated, in the same shape as a synchronous response

462* `failed` (HTTP `200`): `error` holds a `code` and `message`

463

464```python customLanguage="pythonRequests"

465import os

466import time

467import requests

468

469headers = {

470 "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",

471 "Content-Type": "application/json",

472}

473

474# Step 1: Start generation

475response = requests.post(

476 "https://api.x.ai/v1/images/generations",

477 headers=headers,

478 json={

479 "model": "grok-imagine-image-2.0",

480 "prompt": "A serene Japanese garden",

481 "deferred": True,

482 },

483)

484request_id = response.json()["request_id"]

485

486# Step 2: Poll for the result

487while True:

488 result = requests.get(

489 f"https://api.x.ai/v1/images/{request_id}",

490 headers={"Authorization": headers["Authorization"]},

491 )

492 data = result.json()

493

494 if data["status"] == "done":

495 print(f"Image URL: {data['data'][0]['url']}")

496 break

497 elif data["status"] == "failed":

498 print(f"Generation failed: {data['error']['message']}")

499 break

500 else:

501 print("Still processing...")

502 time.sleep(5)

441```503```

442 504

443```bash505```bash

506# Step 1: Start generation

444curl -X POST https://api.x.ai/v1/images/generations \507curl -X POST https://api.x.ai/v1/images/generations \

445 -H "Content-Type: application/json" \508 -H "Content-Type: application/json" \

446 -H "Authorization: Bearer $XAI_API_KEY" \509 -H "Authorization: Bearer $XAI_API_KEY" \

447 -d '{510 -d '{

448 "model": "grok-imagine-image-2.0",511 "model": "grok-imagine-image-2.0",

449 "prompt": "A serene Japanese garden",512 "prompt": "A serene Japanese garden",

450 "response_format": "b64_json"513 "deferred": true

451 }'514 }'

515# => {"request_id": "..."}

516

517# Step 2: Poll for the result

518curl https://api.x.ai/v1/images/<request_id> \

519 -H "Authorization: Bearer $XAI_API_KEY"

520# => 202 {"request_id": "...", "status": "pending"}

521# => 200 {"request_id": "...", "status": "done", "data": [{"url": "...", "mime_type": "image/jpeg"}], "usage": {...}}

452```522```

453 523

524You can also register a [webhook](/developers/rest-api-reference/management/webhooks) for the `image.generation.completed`, `image.generation.failed`, `image.edit.completed` and `image.edit.failed` events instead of polling.

525

454### Response Details526### Response Details

455 527

456The xAI SDK exposes additional metadata on the response object beyond the image URL or base64 data.528The xAI SDK exposes additional metadata on the response object beyond the image URL or base64 data.

model-capabilities/images/generation.md 2026-10-07 23:59 UTC to 2026-10-08 23:58 UTC

Model Capabilities

Image Generation

Quick Start

Configuration

Multiple Images

Aspect Ratio

Resolution

Quality

Base64 Output

Deferred Generation

Response Details

Concurrent Requests

Related