Endpoint /v1/images/generations: Getting Started

Lesson completed on November 3, 2026 based on the Image Generation page and the xAI Images API reference: default values (aspect_ratio set to auto, resolution to 1k), quality parameter for Imagine 2.0, and JPEG as the default format. Sources: Image Generation · Images API.

Generate Your First Image with the Grok API

The xAI API offers a dedicated endpoint for image generation: POST /v1/images/generations. This endpoint lets you create images from a text description using Grok Imagine models. Whether you want to produce illustrations, marketing visuals, or creative prototypes, it all starts with this endpoint.

In this lesson, you’ll learn how to structure an image generation request and understand the fundamental parameters.

Structure of a Generation Request

Two parameters are enough to generate an image: the model and the prompt. All others have default values, which lets you get a first result in three lines—and that’s exactly what you should do before reading the rest, so you have an image in front of you to relate each parameter to.

from openai import OpenAI
import os

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

response = client.images.generate(
    model="grok-imagine-image",
    prompt="A Breton lighthouse under a starry sky, watercolor style"
)

image_url = response.data[0].url
print(image_url)

The xAI API is compatible with the OpenAI SDK for image generation: you point the base_url to https://api.x.ai/v1, provide your xAI key, and the rest of your code remains unchanged. Keep the scope of this compatibility in mind—it applies to generation, but not to editing, which expects a different format. Lesson 5 covers this.

Request Parameters

Here are the parameters you can include in your request:

• model: the generation model to use (grok-imagine-image or grok-imagine-image-2.0, see lesson 2)
• prompt: the text description of the desired image
• n: the number of images to generate (1 to 10, default: 1)
• aspect_ratio: the aspect ratio of the image (auto by default: the model chooses based on the prompt)
• resolution: the resolution (1k by default, or 2k)
• quality: low, medium, or auto (default) on Imagine 2.0, see lesson 12
• response_format: url (default) or b64_json to receive the image in Base64

Example with All Parameters

response = client.images.generate(
    model="grok-imagine-image",
    prompt="An enchanted forest with fireflies, digital art style",
    n=2,
    response_format="url",
    extra_body={"aspect_ratio": "16:9", "resolution": "2k"},
)

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

Response Format

The response is always an array, even for a single image—iterate over it rather than reading data[0], otherwise your code will break the day you set n=4. Each object contains:

• url: the temporary URL of the image (if response_format is url)
• b64_json: the Base64 data of the image (if response_format is b64_json)

The returned MIME type can be image/png, image/jpeg, or image/webp; it defaults to image/jpeg, unless a quality setting produces PNG.

Hands-On Practice

Try generating your first image by adapting the prompt to your professional context. For example, for a presentation visual:

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Minimalist chart showing startup growth, "
           "blue and white colors, dark background, flat design style",
    extra_body={"resolution": "2k", "aspect_ratio": "16:9"},
)

Key Takeaways

• The generation endpoint is POST /v1/images/generations
• Two parameters are enough to start: model and prompt
• The API is compatible with the OpenAI Python SDK by changing the base_url
• You can generate up to 10 images per request
• The available resolutions are 1k (default) and 2k