Generate image variations with the Imagine API

Ask the Imagine API for several stills from the same prompt in one request so you can pick a favorite without firing separate calls. Official Image Generation documents the n parameter (1–10) on POST https://api.x.ai/v1/images/generations, and the xAI Python SDK exposes sample_batch(n=...) for the same job. Model id for current Quality Mode parity is grok-imagine-image-2.0. Create a key and load credits at console.x.ai before you bill the first batch.

What you need

An XAI_API_KEY with Console balance, a concrete prompt (subject, verb, light, what stays out of frame), and a decision on how many variations you want in this batch. Same-prompt variations belong in one n request. Different prompts in parallel should use concurrent clients instead — the docs tip says sample_batch() with n is the efficient path when the prompt is shared.

Generate the batch

1. Export the key locally and keep it out of chat logs and public repos:

export XAI_API_KEY="your_api_key"

2. Call the generations endpoint with model, prompt, and n set to the variation count you want (example uses four):

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, sharp neon edges, clear horizon",
    "n": 4
  }'

3. Or use the xAI Python SDK batch helper:

import os
import xai_sdk

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

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

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

4. Download or process each returned URL promptly — hosted image URLs are temporary.
5. Keep the winning variation URL or bytes, then optionally lock aspect ratio or quality on the next request with Set aspect ratio on Imagine API images before you edit further via Edit an image with the Imagine API.

OpenAI-compatible clients point base_url at https://api.x.ai/v1 and pass n on images.generate. The Vercel AI SDK generateImage path also accepts n for multiple outputs in one call.

After you pick a winner

Save the chosen still locally, and only then chain an edit or a Smart-resize-style consumer pass if the placement needs a different frame. When each image needs a different prompt, fire concurrent sample() calls with AsyncClient and asyncio.gather instead of raising n on a single shared prompt. For the consumer Quality Mode loop on grok.com without API keys, start at Open Imagine Quality Mode and iterate a still.

Pitfalls

Leaving n at the default of 1 when you meant a batch wastes round trips. Raising n above what you will actually review burns credits on unread URLs. Pasting the API key into a ticket or a screenshot is a revoke-and-rotate event. Treating Console API credits as the same bucket as SuperGrok's weekly Imagine pool on grok.com mixes two billing surfaces the FAQ and Console docs keep separate. Waiting on temporary URLs without downloading them first loses the variation you meant to keep.