10 10
11| SDK/API | Tool Name |11| SDK/API | Tool Name |
12|---------|-----------|12|---------|-----------|
13| xAI SDK | `image_generation` |
13| OpenAI Responses API | `image_generation` |14| OpenAI Responses API | `image_generation` |
14 15
15This tool is also supported in all Responses API compatible SDKs. The Vercel AI SDK does not yet expose the image generation tool.16This tool is also supported in all Responses API compatible SDKs. The Vercel AI SDK does not yet expose the image generation tool.
16 17
17## Basic usage18## Basic usage
18 19
19Add `image_generation` to `tools` and ask for an image. In the Responses API, each image arrives as an `image_generation_call` output item whose `result` field carries the base64-encoded image with no data-URL prefix, so you can decode it directly.20Add `image_generation` to `tools` and ask for an image. In the xAI SDK, each generated image is exposed on `response.image_outputs` as decoded bytes you can write straight to a file. In the Responses API, each image arrives as an `image_generation_call` output item whose `result` field carries the base64-encoded image with no data-URL prefix, so you can decode it directly.
20 21
21```bash customLanguage="bash"22```bash customLanguage="bash"
22curl https://api.x.ai/v1/responses \23curl https://api.x.ai/v1/responses \
34 | base64 --decode > corgi_surfing.jpg35 | base64 --decode > corgi_surfing.jpg
35```36```
36 37
38```python customLanguage="pythonXAI"
39import os
40
41from xai_sdk import Client
42from xai_sdk.chat import user
43from xai_sdk.tools import image_generation
44
45client = Client(api_key=os.getenv("XAI_API_KEY"))
46
47chat = client.chat.create(
48 model="grok-4.6",
49 tools=[image_generation()],
50)
51chat.append(user("Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print"))
52response = chat.sample()
53
54print(response.content)
55with open("image.jpeg", "wb") as f:
56 f.write(response.image_outputs[0].image)
57```
58
37```python customLanguage="pythonOpenAISDK"59```python customLanguage="pythonOpenAISDK"
38import base6460import base64
39import os61import os
156}'178}'
157```179```
158 180
181```python customLanguage="pythonXAI"
182chat = client.chat.create(
183 model="grok-4.6",
184 tools=[image_generation(action="generate")],
185)
186chat.append(user("Generate an image of a hot air balloon over the desert"))
187response = chat.sample()
188```
189
159```python customLanguage="pythonOpenAISDK"190```python customLanguage="pythonOpenAISDK"
160response = client.responses.create(191response = client.responses.create(
161 model="grok-4.6",192 model="grok-4.6",
198}'229}'
199```230```
200 231
232```python customLanguage="pythonXAI"
233import os
234
235from xai_sdk import Client
236from xai_sdk.chat import image, user
237from xai_sdk.tools import image_generation
238
239client = Client(api_key=os.getenv("XAI_API_KEY"))
240
241chat = client.chat.create(
242 model="grok-4.6",
243 tools=[image_generation(action="edit")],
244)
245chat.append(
246 user(
247 "Edit this image so it looks like a watercolor painting.",
248 image("https://docs.x.ai/assets/api-examples/images/style-realistic.png"),
249 )
250)
251response = chat.sample()
252
253with open("image.jpeg", "wb") as f:
254 f.write(response.image_outputs[0].image)
255```
256
201```python customLanguage="pythonOpenAISDK"257```python customLanguage="pythonOpenAISDK"
202import base64258import base64
203import os259import os
242 298
243## Multi-turn editing299## Multi-turn editing
244 300
245Images generated on a previous turn stay editable on follow-up turns. Continue the conversation with `previous_response_id`, and the model can refine its earlier images by reference:301Images generated on a previous turn stay editable on follow-up turns. Continue the conversation — append the previous response to the chat in the xAI SDK, or pass `previous_response_id` in the Responses API — and the model can refine its earlier images by reference:
302
303```python customLanguage="pythonXAI"
304import os
305
306from xai_sdk import Client
307from xai_sdk.chat import user
308from xai_sdk.tools import image_generation
309
310client = Client(api_key=os.getenv("XAI_API_KEY"))
311
312chat = client.chat.create(
313 model="grok-4.6",
314 tools=[image_generation()],
315)
316
317# Turn 1: generate an image
318chat.append(user("Generate an image of a lighthouse on a rocky coast"))
319response = chat.sample()
320with open("image.jpeg", "wb") as f:
321 f.write(response.image_outputs[0].image)
322
323# Turn 2: edit the image from the previous turn
324chat.append(response)
325chat.append(user("Make it night time with a full moon"))
326followup = chat.sample()
327with open("edited_image.jpeg", "wb") as f:
328 f.write(followup.image_outputs[0].image)
329```
246 330
247```python customLanguage="pythonOpenAISDK"331```python customLanguage="pythonOpenAISDK"
248import base64332import base64
315 | base64 --decode > champions_poster.jpg399 | base64 --decode > champions_poster.jpg
316```400```
317 401
402```python customLanguage="pythonXAI"
403import os
404
405from xai_sdk import Client
406from xai_sdk.chat import user
407from xai_sdk.tools import image_generation, web_search
408
409client = Client(api_key=os.getenv("XAI_API_KEY"))
410
411chat = client.chat.create(
412 model="grok-4.6",
413 tools=[web_search(), image_generation()],
414)
415chat.append(
416 user(
417 "Find out which team won the most recent FIFA World Cup, then generate an "
418 "image of a celebratory poster for that team, in a vintage travel-poster style."
419 )
420)
421response = chat.sample()
422
423print(response.content)
424with open("image.jpeg", "wb") as f:
425 f.write(response.image_outputs[0].image)
426
427# Per-tool invocation counts for the request
428print(response.server_side_tool_usage)
429```
430
318```python customLanguage="pythonOpenAISDK"431```python customLanguage="pythonOpenAISDK"
319import base64432import base64
320import os433import os
357 470
358When streaming, each image generation call emits progress events—`in_progress`, then `generating`, then `completed`—followed by a `response.output_item.done` event whose item carries the base64 result. Partial image previews are not emitted.471When streaming, each image generation call emits progress events—`in_progress`, then `generating`, then `completed`—followed by a `response.output_item.done` event whose item carries the base64 result. Partial image previews are not emitted.
359 472
473In the xAI SDK, pass `include=["verbose_streaming"]` to watch tool calls as they happen; the decoded images are available on the accumulated response via `response.image_outputs` once the stream ends.
474
475```python customLanguage="pythonXAI"
476import os
477
478from xai_sdk import Client
479from xai_sdk.chat import user
480from xai_sdk.tools import get_tool_call_type, image_generation
481
482client = Client(api_key=os.getenv("XAI_API_KEY"))
483
484chat = client.chat.create(
485 model="grok-4.6",
486 tools=[image_generation()],
487 include=["verbose_streaming"],
488)
489chat.append(user("Generate an image of an origami fox in a paper forest"))
490
491for response, chunk in chat.stream():
492 for tool_call in chunk.tool_calls:
493 if get_tool_call_type(tool_call) == "image_generation_tool":
494 print(f"\nGenerating image: {tool_call.function.arguments}")
495 if chunk.content:
496 print(chunk.content, end="", flush=True)
497
498# The accumulated response carries the decoded images once the stream ends
499with open("image.jpeg", "wb") as f:
500 f.write(response.image_outputs[0].image)
501```
502
360```python customLanguage="pythonOpenAISDK"503```python customLanguage="pythonOpenAISDK"
361import base64504import base64
362import os505import os
