Image Generation

Generate images from text prompts, edit existing images with natural language, or iteratively refine images through multi-turn conversations. The API supports batch generation of multiple images, and control over aspect ratio and resolution.

Generate an image with a single API call:

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",
)

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.

Edit an existing image by providing a source image along with your prompt. The model understands the image content and applies your requested changes.

With the xAI SDK, use the same sample() method — just add the image_url parameter:

import base64
import xai_sdk

client = xai_sdk.Client()

# Load image from file and encode as base64
with open("landmarks.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.image.sample(
    prompt="Change the landmarks to be New York City landmarks",
    model="grok-imagine-image",
    image_url=f"data:image/jpeg;base64,{image_data}",
)

print(response.url)

You can provide the source image as:

• A public URL pointing to an image
• A base64-encoded data URI (e.g., data:image/jpeg;base64,...)

Chain multiple edits together by using each output as the input for the next. This enables iterative refinement — start with a base image and progressively add details, adjust styles, or make corrections.

Python

Other

import xai_sdkclient = xai_sdk.Client()response = client.image.sample(    prompt="A modern living room with large windows overlooking the city",                            model="grok-imagine-image",)    print(response.url)

1. Initial2. Modify Furniture3. Adjust lighting

The grok-imagine-image model excels across a wide range of visual styles — from ultra-realistic photography to anime, oil paintings, pencil sketches, and beyond. Transform existing images by simply describing the desired aesthetic in your prompt.

Original

Oil Painting

Python

Other

import xai_sdkclient = xai_sdk.Client()response = client.image.sample(    prompt="Render this image as an oil painting in the style of impressionism",    model="grok-imagine-image",    image_url="https://docs.x.ai/assets/api-examples/images/style-realistic.png",)print(response.url)

Oil PaintingPencil SketchPop ArtAnimeWatercolor

When you need to generate multiple images with different prompts — such as applying various style transfers to the same source image, or 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.

import asyncio
import xai_sdk

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

    source_image = "https://example.com/portrait.jpg"

    # Each request uses a different prompt
    prompts = [
        "Render this image as an oil painting in the style of impressionism",
        "Render this image as a pencil sketch with detailed shading",
        "Render this image as pop art with bold colors and halftone dots",
        "Render this image as a watercolor painting with soft edges",
    ]

    # Fire all requests concurrently
    tasks = [
        client.image.sample(
            prompt=prompt,
            model="grok-imagine-image",
            image_url=source_image,
        )
        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())

Generate multiple images in a single request using the sample_batch() method and the n parameter. This returns a list of ImageResponse objects.

import xai_sdk

client = xai_sdk.Client()

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

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

Control image dimensions with the aspect_ratio parameter:

import xai_sdk

client = xai_sdk.Client()

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

print(response.url)

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

• 1k
• 2k

import xai_sdk

client = xai_sdk.Client()

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

For embedding images directly without downloading, request base64:

import xai_sdk

client = xai_sdk.Client()

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

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

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}")

Image generation uses flat per-image pricing rather than token-based pricing like text models. Each generated image incurs a fixed fee regardless of prompt length.

For image editing, you are charged for both the input image and the generated output image.

For full pricing details on the grok-imagine-image model, see the model page.

• Maximum images per request: 10
• URL expiration: Generated URLs are temporary
• Content moderation: Images are subject to content policy review

• Models — Available image models
• Video Generation — Animate generated images
• API Reference — Full endpoint documentation