SPB Git

Repository Public

image-generation.md 18.0 KB 576 lines markdown

1<!-- source: https://docs.x.ai/developers/tools/image-generation (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Tools34# Image Generation Tool56The image generation tool lets Grok create and edit images with [Grok Imagine](/developers/model-capabilities/images/generation) as part of a conversation. It uses the latest Imagine image models (`grok-imagine-image-2.0`). You hand the model the tool; it decides when to call it, writes the image prompt, picks an aspect ratio, and returns the finished image alongside its text response. Because the tool runs server-side, the model can also chain calls—generating an image and then editing it—within a single request.78If you already have the exact prompt and want direct control over aspect ratio and resolution, call the [image generation](/developers/model-capabilities/images/generation) and [image editing](/developers/model-capabilities/images/editing) endpoints instead. Reach for the tool when image creation is one step in a larger conversational or agentic workflow.910## SDK support1112| SDK/API | Tool Name |13|---------|-----------|14| xAI SDK | `image_generation` |15| OpenAI Responses API | `image_generation` |1617This tool is also supported in all Responses API compatible SDKs. The Vercel AI SDK does not yet expose the image generation tool.1819## Basic usage2021Add `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.2223```bash customLanguage="bash"24curl https://api.x.ai/v1/responses \25  -H "Content-Type: application/json" \26  -H "Authorization: Bearer $XAI_API_KEY" \27  -d '{28  "model": "grok-4.6",29  "input": "Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",30  "tools": [31    {32      "type": "image_generation"33    }34  ]35}' | jq -r '.output[] | select(.type == "image_generation_call") | .result' \36  | base64 --decode > corgi_surfing.jpg37```3839```python customLanguage="pythonXAI"40import os4142from xai_sdk import Client43from xai_sdk.chat import user44from xai_sdk.tools import image_generation4546client = Client(api_key=os.getenv("XAI_API_KEY"))4748chat = client.chat.create(49    model="grok-4.6",50    tools=[image_generation()],51)52chat.append(user("Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print"))53response = chat.sample()5455print(response.content)56with open("image.jpeg", "wb") as f:57    f.write(response.image_outputs[0].image)58```5960```python customLanguage="pythonOpenAISDK"61import base6462import os6364from openai import OpenAI6566client = OpenAI(67    api_key=os.getenv("XAI_API_KEY"),68    base_url="https://api.x.ai/v1",69)7071response = client.responses.create(72    model="grok-4.6",73    input="Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",74    tools=[{"type": "image_generation"}],75)7677image_data = [78    output.result79    for output in response.output80    if output.type == "image_generation_call"81]8283if image_data:84    with open("corgi_surfing.jpg", "wb") as f:85        f.write(base64.b64decode(image_data[0]))86```8788```python customLanguage="pythonRequests"89import base6490import os9192import requests9394url = "https://api.x.ai/v1/responses"95headers = {96    "Content-Type": "application/json",97    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",98}99payload = {100    "model": "grok-4.6",101    "input": "Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",102    "tools": [{"type": "image_generation"}],103}104response = requests.post(url, headers=headers, json=payload)105data = response.json()106107for item in data["output"]:108    if item["type"] == "image_generation_call":109        with open("corgi_surfing.jpg", "wb") as f:110            f.write(base64.b64decode(item["result"]))111```112113```javascript customLanguage="javascriptOpenAISDK"114import fs from "fs";115import OpenAI from "openai";116117const client = new OpenAI({118  apiKey: process.env.XAI_API_KEY,119  baseURL: "https://api.x.ai/v1",120});121122const response = await client.responses.create({123  model: "grok-4.6",124  input:125    "Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",126  tools: [{ type: "image_generation" }],127});128129const imageData = response.output130  .filter((output) => output.type === "image_generation_call")131  .map((output) => output.result);132133if (imageData.length > 0) {134  fs.writeFileSync("corgi_surfing.jpg", Buffer.from(imageData[0], "base64"));135}136```137138A completed `image_generation_call` output item looks like this:139140```json141{142  "type": "image_generation_call",143  "id": "ig_d817cfd0-4f39-9cb3-bda2-44e538841ef2_call-a1b4dd05",144  "status": "completed",145  "prompt": "A corgi surfing a big wave, Japanese woodblock print style",146  "result": "/9j/4AAQSkZJRgABAQAAAQABAAD..."147}148```149150The `prompt` field shows the prompt the model wrote for the image model, useful for understanding and debugging what was generated. Item IDs are prefixed `ig_` for generations and `ie_` for edits.151152The tool takes no size or format parameters; the model picks an aspect ratio for each call. To control it, ask in your request ("in a 9:16 vertical aspect ratio") and the generated image will match.153154## The action parameter155156By default the model can both generate new images and edit existing ones. The optional `action` parameter restricts this:157158| Action | Behavior |159|--------|----------|160| `auto` | Default. The model can generate and edit images |161| `generate` | Text-to-image generation only |162| `edit` | Image editing only |163164For example, to let the model create images but never modify ones already in the conversation:165166```bash customLanguage="bash"167curl https://api.x.ai/v1/responses \168  -H "Content-Type: application/json" \169  -H "Authorization: Bearer $XAI_API_KEY" \170  -d '{171  "model": "grok-4.6",172  "input": "Generate an image of a hot air balloon over the desert",173  "tools": [174    {175      "type": "image_generation",176      "action": "generate"177    }178  ]179}'180```181182```python customLanguage="pythonXAI"183chat = client.chat.create(184    model="grok-4.6",185    tools=[image_generation(action="generate")],186)187chat.append(user("Generate an image of a hot air balloon over the desert"))188response = chat.sample()189```190191```python customLanguage="pythonOpenAISDK"192response = client.responses.create(193    model="grok-4.6",194    input="Generate an image of a hot air balloon over the desert",195    tools=[{"type": "image_generation", "action": "generate"}],196)197```198199## Editing input images200201With `action` set to `edit` (or the default `auto`), the model can edit any image already in the conversation: images you attach as input as well as images it generated earlier. Edits produce `image_generation_call` items with an `ie_` ID prefix.202203```bash customLanguage="bash"204curl https://api.x.ai/v1/responses \205  -H "Content-Type: application/json" \206  -H "Authorization: Bearer $XAI_API_KEY" \207  -d '{208  "model": "grok-4.6",209  "input": [210    {211      "role": "user",212      "content": [213        {214          "type": "input_text",215          "text": "Edit this image so it looks like a watercolor painting."216        },217        {218          "type": "input_image",219          "image_url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png"220        }221      ]222    }223  ],224  "tools": [225    {226      "type": "image_generation",227      "action": "edit"228    }229  ]230}'231```232233```python customLanguage="pythonXAI"234import os235236from xai_sdk import Client237from xai_sdk.chat import image, user238from xai_sdk.tools import image_generation239240client = Client(api_key=os.getenv("XAI_API_KEY"))241242chat = client.chat.create(243    model="grok-4.6",244    tools=[image_generation(action="edit")],245)246chat.append(247    user(248        "Edit this image so it looks like a watercolor painting.",249        image("https://docs.x.ai/assets/api-examples/images/style-realistic.png"),250    )251)252response = chat.sample()253254with open("image.jpeg", "wb") as f:255    f.write(response.image_outputs[0].image)256```257258```python customLanguage="pythonOpenAISDK"259import base64260import os261262from openai import OpenAI263264client = OpenAI(265    api_key=os.getenv("XAI_API_KEY"),266    base_url="https://api.x.ai/v1",267)268269response = client.responses.create(270    model="grok-4.6",271    input=[272        {273            "role": "user",274            "content": [275                {276                    "type": "input_text",277                    "text": "Edit this image so it looks like a watercolor painting.",278                },279                {280                    "type": "input_image",281                    "image_url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png",282                },283            ],284        }285    ],286    tools=[{"type": "image_generation", "action": "edit"}],287)288289image_data = [290    output.result291    for output in response.output292    if output.type == "image_generation_call"293]294295if image_data:296    with open("watercolor.jpg", "wb") as f:297        f.write(base64.b64decode(image_data[0]))298```299300## Multi-turn editing301302Images 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:303304```python customLanguage="pythonXAI"305import os306307from xai_sdk import Client308from xai_sdk.chat import user309from xai_sdk.tools import image_generation310311client = Client(api_key=os.getenv("XAI_API_KEY"))312313chat = client.chat.create(314    model="grok-4.6",315    tools=[image_generation()],316)317318# Turn 1: generate an image319chat.append(user("Generate an image of a lighthouse on a rocky coast"))320response = chat.sample()321with open("image.jpeg", "wb") as f:322    f.write(response.image_outputs[0].image)323324# Turn 2: edit the image from the previous turn325chat.append(response)326chat.append(user("Make it night time with a full moon"))327followup = chat.sample()328with open("edited_image.jpeg", "wb") as f:329    f.write(followup.image_outputs[0].image)330```331332```python customLanguage="pythonOpenAISDK"333import base64334import os335336from openai import OpenAI337338client = OpenAI(339    api_key=os.getenv("XAI_API_KEY"),340    base_url="https://api.x.ai/v1",341)342343response = client.responses.create(344    model="grok-4.6",345    input="Generate an image of a lighthouse on a rocky coast",346    tools=[{"type": "image_generation"}],347)348349image_data = [350    output.result351    for output in response.output352    if output.type == "image_generation_call"353]354355if image_data:356    with open("lighthouse.jpg", "wb") as f:357        f.write(base64.b64decode(image_data[0]))358359# Follow up: edit the image from the previous turn360followup = client.responses.create(361    model="grok-4.6",362    previous_response_id=response.id,363    input="Make it night time with a full moon",364    tools=[{"type": "image_generation"}],365)366367image_data_followup = [368    output.result369    for output in followup.output370    if output.type == "image_generation_call"371]372373if image_data_followup:374    with open("lighthouse_night.jpg", "wb") as f:375        f.write(base64.b64decode(image_data_followup[0]))376```377378If you manage conversation state yourself instead of using `previous_response_id`, pass the previous turn's output items (including the `image_generation_call` items) back verbatim in `input`; the images they carry remain editable on the next request.379380## Combining with other tools381382The image generation tool composes with the other server-side tools. Include several tools in the same request and the model orchestrates them within a single agentic loop, feeding what one tool found into the next. Here it looks up a fact with [web search](/developers/tools/web-search) first, then writes an image prompt from what it learned:383384```bash customLanguage="bash"385curl https://api.x.ai/v1/responses \386  -H "Content-Type: application/json" \387  -H "Authorization: Bearer $XAI_API_KEY" \388  -d '{389  "model": "grok-4.6",390  "input": "Find out which team won the most recent FIFA World Cup, then generate an image of a celebratory poster for that team, in a vintage travel-poster style.",391  "tools": [392    {393      "type": "web_search"394    },395    {396      "type": "image_generation"397    }398  ]399}' | jq -r '.output[] | select(.type == "image_generation_call") | .result' \400  | base64 --decode > champions_poster.jpg401```402403```python customLanguage="pythonXAI"404import os405406from xai_sdk import Client407from xai_sdk.chat import user408from xai_sdk.tools import image_generation, web_search409410client = Client(api_key=os.getenv("XAI_API_KEY"))411412chat = client.chat.create(413    model="grok-4.6",414    tools=[web_search(), image_generation()],415)416chat.append(417    user(418        "Find out which team won the most recent FIFA World Cup, then generate an "419        "image of a celebratory poster for that team, in a vintage travel-poster style."420    )421)422response = chat.sample()423424print(response.content)425with open("image.jpeg", "wb") as f:426    f.write(response.image_outputs[0].image)427428# Per-tool invocation counts for the request429print(response.server_side_tool_usage)430```431432```python customLanguage="pythonOpenAISDK"433import base64434import os435436from openai import OpenAI437438client = OpenAI(439    api_key=os.getenv("XAI_API_KEY"),440    base_url="https://api.x.ai/v1",441)442443response = client.responses.create(444    model="grok-4.6",445    input=(446        "Find out which team won the most recent FIFA World Cup, then generate an "447        "image of a celebratory poster for that team, in a vintage travel-poster style."448    ),449    tools=[450        {"type": "web_search"},451        {"type": "image_generation"},452    ],453)454455for output in response.output:456    if output.type == "web_search_call":457        print(f"Web search: {output.action}")458    elif output.type == "image_generation_call":459        print(f"Image prompt: {output.prompt}")460        with open("champions_poster.jpg", "wb") as f:461            f.write(base64.b64decode(output.result))462    elif output.type == "message":463        print(output.content[0].text)464```465466The response output interleaves the tool calls in the order they ran: a `web_search_call` item, a message answering the factual question with citations, and an `image_generation_call` item carrying the poster.467468The same pattern works with [X search](/developers/tools/x-search), [code execution](/developers/tools/code-execution), and your own client-side functions. See [Advanced Usage](/developers/tools/advanced-usage#tool-combinations) for more tool combination patterns.469470## Streaming471472When 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.473474In 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.475476```python customLanguage="pythonXAI"477import os478479from xai_sdk import Client480from xai_sdk.chat import user481from xai_sdk.tools import get_tool_call_type, image_generation482483client = Client(api_key=os.getenv("XAI_API_KEY"))484485chat = client.chat.create(486    model="grok-4.6",487    tools=[image_generation()],488    include=["verbose_streaming"],489)490chat.append(user("Generate an image of an origami fox in a paper forest"))491492for response, chunk in chat.stream():493    for tool_call in chunk.tool_calls:494        if get_tool_call_type(tool_call) == "image_generation_tool":495            print(f"\nGenerating image: {tool_call.function.arguments}")496    if chunk.content:497        print(chunk.content, end="", flush=True)498499# The accumulated response carries the decoded images once the stream ends500with open("image.jpeg", "wb") as f:501    f.write(response.image_outputs[0].image)502```503504```python customLanguage="pythonOpenAISDK"505import base64506import os507508from openai import OpenAI509510client = OpenAI(511    api_key=os.getenv("XAI_API_KEY"),512    base_url="https://api.x.ai/v1",513)514515stream = client.responses.create(516    model="grok-4.6",517    input="Generate an image of an origami fox in a paper forest",518    tools=[{"type": "image_generation"}],519    stream=True,520)521522for event in stream:523    if event.type.startswith("response.image_generation_call."):524        # in_progress -> generating -> completed525        print(f"Image generation status: {event.type.rsplit('.', 1)[-1]}")526    elif event.type == "response.output_item.done" and event.item.type == "image_generation_call":527        # The base64 image rides on the final output item528        with open("origami_fox.jpg", "wb") as f:529            f.write(base64.b64decode(event.item.result))530    elif event.type == "response.output_text.delta":531        print(event.delta, end="", flush=True)532```533534```javascript customLanguage="javascriptOpenAISDK"535import fs from "fs";536import OpenAI from "openai";537538const client = new OpenAI({539  apiKey: process.env.XAI_API_KEY,540  baseURL: "https://api.x.ai/v1",541});542543const stream = await client.responses.create({544  model: "grok-4.6",545  input: "Generate an image of an origami fox in a paper forest",546  tools: [{ type: "image_generation" }],547  stream: true,548});549550for await (const event of stream) {551  if (event.type.startsWith("response.image_generation_call.")) {552    // in_progress -> generating -> completed553    console.log(`Image generation status: ${event.type.split(".").pop()}`);554  } else if (555    event.type === "response.output_item.done" &&556    event.item.type === "image_generation_call"557  ) {558    // The base64 image rides on the final output item559    fs.writeFileSync(560      "origami_fox.jpg",561      Buffer.from(event.item.result, "base64")562    );563  } else if (event.type === "response.output_text.delta") {564    process.stdout.write(event.delta);565  }566}567```568569## Related570571* [Image Generation](/developers/model-capabilities/images/generation) — Generate images directly with the images endpoint572* [Image Editing](/developers/model-capabilities/images/editing) — Edit images with natural language573* [Tools Overview](/developers/tools/overview) — All built-in tools574* [Streaming & Sync](/developers/tools/streaming-and-sync) — Streaming behavior of tool-enabled requests575* [Pricing](/developers/pricing#tools-pricing) — Tool invocation costs576
Files main
Menu

Theme