Use the image generation tool in a conversation

Add image_generation to tools on POST https://api.x.ai/v1/responses. Grok writes the image prompt, picks an aspect ratio, and returns the still on an image_generation_call item. The image model is grok-imagine-image-2.0. Chat model in the examples is grok-4.6.

The tool takes no size or format parameters. Ask for a ratio in the user text ("9:16 vertical") and the still matches. Vercel AI SDK does not expose this tool yet.

One request

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.6",
    "input": "Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",
    "tools": [{"type": "image_generation"}]
  }' | jq -r '.output[] | select(.type == "image_generation_call") | .result' \
  | base64 --decode > corgi_surfing.jpg

Python SDK:

import os
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import image_generation

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(model="grok-4.6", tools=[image_generation()])
chat.append(user("Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print"))
response = chat.sample()
with open("image.jpeg", "wb") as f:
    f.write(response.image_outputs[0].image)

result on image_generation_call is raw base64 with no data-URL prefix. Item ids start with ig_ for generations and ie_ for edits. prompt on that item is the prompt Grok wrote for Imagine.

action on the tool: auto (default, generate and edit), generate, or edit. Attach an input_image and set action: "edit" to rewrite a still you sent. Pass previous_response_id (or append the prior response in the xAI SDK) to edit an image from the last turn.

You can put web_search and image_generation in the same tools list. Grok can look something up, then draw from what it found.

If you already have the exact prompt and want to set aspect_ratio and resolution yourself, call /v1/images/generations or /v1/images/edits directly.

Pitfalls

• Streaming emits in_progress → generating → completed. Partial previews are not sent. The base64 lands on response.output_item.done.
• The Vercel AI SDK does not expose image_generation yet. Use the xAI SDK, the OpenAI Responses client pointed at https://api.x.ai/v1, or raw HTTP.
• Console API credits are a separate bill from SuperGrok's weekly pool on grok.com.