DocsAPI ReferencePricing

Model Capabilities

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.

Quick Start

Generate an image with a single API call:

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    "A golden retriever playing fetch on a sunny beach at sunset",
    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.

Image Editing

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

Note: The OpenAI SDK's images.edit() method is not supported for image editing because it uses multipart/form-data, while the xAI API requires application/json. Use the xAI SDK, Vercel AI SDK, or direct HTTP requests instead.

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("beach-dog.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.image.sample(
    "Change the golden retriever to a black labrador",
    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,...)

Multi-Turn Editing

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

import xai_sdk

client = xai_sdk.Client()

image_url = None

while True:
    prompt = input("Enter prompt (or 'done' to finish): ")
    if prompt.lower() == "done":
        break
    
    response = client.image.sample(
        prompt,
        model="grok-imagine-image",
        image_url=image_url,  # None for first generation, then previous output
    )
    
    print(f"Generated: {response.url}")
    image_url = response.url  # Use this image as input for next turn

The images below show this workflow in action:

Prompt: A modern living room with large windows overlooking the city
1. Initial

Style Transfer

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.

Using AsyncClient with asyncio.gather lets you process multiple style transfers concurrently, making it significantly faster than sequential requests:

import asyncio
import xai_sdk

async def apply_styles():
    client = xai_sdk.AsyncClient()
    
    source_image = "https://example.com/portrait.jpg"
    
    styles = [
        "ultra-realistic photograph with dramatic lighting",
        "oil painting in the style of impressionism",
        "pencil sketch with detailed shading",
        "pop art with bold colors and halftone dots",
        "anime illustration style",
        "watercolor painting with soft edges",
    ]
    
    # Process all styles concurrently
    tasks = [
        client.image.sample(
            f"Render this image as a {style}",
            model="grok-imagine-image",
            image_url=source_image,
        )
        for style in styles
    ]
    
    results = await asyncio.gather(*tasks)
    
    for style, result in zip(styles, results):
        print(f"{style}: {result.url}")

asyncio.run(apply_styles())
Original
Oil Painting
Original
Oil Painting

Configuration

Multiple Images

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

Aspect Ratio

Control image dimensions with the aspect_ratio parameter:

RatioUse case
1:1Social media, thumbnails
16:9 / 9:16Widescreen, mobile, stories
4:3 / 3:4Presentations, portraits
3:2 / 2:3Photography
2:1 / 1:2Banners, headers
19.5:9 / 9:19.5Modern smartphone displays
20:9 / 9:20Ultra-wide displays
import xai_sdk

client = xai_sdk.Client()

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

print(response.url)

Base64 Output

For embedding images directly without downloading, request base64:

import xai_sdk

client = xai_sdk.Client()

response = client.image.sample(
    "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)

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:

Python

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

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

Python

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

Pricing

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.

Limitations

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

Related