Image generation tool 使 Grok 可以在 conversation 中使用 Grok Imagine 创建和编辑图像。该 tool 使用最新的 Imagine image model（grok-imagine-image-quality）。你将 tool 提供给 model，model 会决定何时调用、编写 image prompt、选择 aspect ratio，并将最终图像与文本 response 一并返回。由于 tool 在服务端运行，model 还可以在单个请求中串联调用，例如先生成图像，再编辑图像。

如果已经有精确 prompt，并希望直接控制 aspect ratio 和 resolution，请改用 image generation 和 image editing endpoint。当图像创建是更大 conversation 或 agentic workflow 中的一个步骤时，再使用该 tool。

SDK 支持

SDK/API	Tool 名称
OpenAI Responses API	`image_generation`

所有与 Responses API 兼容的 SDK 也支持该 tool。Vercel AI SDK 尚未公开 image generation tool。

基础用法

将 image_generation 添加到 tools 并请求图像。在 Responses API 中，每张图像都以 image_generation_call output item 的形式返回，其 result 字段包含不带 data-URL prefix 的 base64 编码图像，因此可以直接解码。

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.5",
  "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

import base64
import os

from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.5",
    input="Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",
    tools=[{"type": "image_generation"}],
)

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("corgi_surfing.jpg", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

import base64
import os

import requests

url = "https://api.x.ai/v1/responses"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
}
payload = {
    "model": "grok-4.5",
    "input": "Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",
    "tools": [{"type": "image_generation"}],
}
response = requests.post(url, headers=headers, json=payload)
data = response.json()

for item in data["output"]:
    if item["type"] == "image_generation_call":
        with open("corgi_surfing.jpg", "wb") as f:
            f.write(base64.b64decode(item["result"]))

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const response = await client.responses.create({
  model: "grok-4.5",
  input:
    "Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print",
  tools: [{ type: "image_generation" }],
});

const imageData = response.output
  .filter((output) => output.type === "image_generation_call")
  .map((output) => output.result);

if (imageData.length > 0) {
  fs.writeFileSync("corgi_surfing.jpg", Buffer.from(imageData[0], "base64"));
}

一个完整的 image_generation_call output item 如下所示：

{
  "type": "image_generation_call",
  "id": "ig_d817cfd0-4f39-9cb3-bda2-44e538841ef2_call-a1b4dd05",
  "status": "completed",
  "prompt": "A corgi surfing a big wave, Japanese woodblock print style",
  "result": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

其中 prompt 字段显示 model 为 image model 编写的 prompt，有助于理解和调试生成内容。Generation item ID 以 ig_ 为 prefix，edit item ID 以 ie_ 为 prefix。

该 tool 不接受 size 或 format 参数；model 会为每次调用选择 aspect ratio。如需控制，请在请求中明确说明（例如“使用 9:16 竖向 aspect ratio”），生成图像会与之匹配。

action 参数

默认情况下，model 既可以生成新图像，也可以编辑现有图像。可选的 action 参数可以限制该行为：

Action	行为
`auto`	默认。Model 可以生成和编辑图像
`generate`	仅 text-to-image generation
`edit`	仅 image editing

例如，允许 model 创建图像，但绝不修改 conversation 中已有的图像：

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.5",
  "input": "Generate an image of a hot air balloon over the desert",
  "tools": [
    {
      "type": "image_generation",
      "action": "generate"
    }
  ]
}'

response = client.responses.create(
    model="grok-4.5",
    input="Generate an image of a hot air balloon over the desert",
    tools=[{"type": "image_generation", "action": "generate"}],
)

编辑输入图像

当 action 设置为 edit（或使用默认的 auto）时，model 可以编辑 conversation 中的任意已有图像，包括作为输入附加的图像和之前生成的图像。Edit 会生成 image_generation_call item，其 ID 使用 ie_ prefix。

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.5",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Edit this image so it looks like a watercolor painting."
        },
        {
          "type": "input_image",
          "image_url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "image_generation",
      "action": "edit"
    }
  ]
}'

import base64
import os

from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.5",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Edit this image so it looks like a watercolor painting.",
                },
                {
                    "type": "input_image",
                    "image_url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png",
                },
            ],
        }
    ],
    tools=[{"type": "image_generation", "action": "edit"}],
)

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("watercolor.jpg", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

Multi-turn editing

在上一 turn 生成的图像可在后续 turn 中继续编辑。使用 previous_response_id 继续 conversation，model 即可通过引用细化之前的图像：

import base64
import os

from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.5",
    input="Generate an image of a lighthouse on a rocky coast",
    tools=[{"type": "image_generation"}],
)

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("lighthouse.jpg", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

# Follow up: edit the image from the previous turn
followup = client.responses.create(
    model="grok-4.5",
    previous_response_id=response.id,
    input="Make it night time with a full moon",
    tools=[{"type": "image_generation"}],
)

image_data_followup = [
    output.result
    for output in followup.output
    if output.type == "image_generation_call"
]

if image_data_followup:
    with open("lighthouse_night.jpg", "wb") as f:
        f.write(base64.b64decode(image_data_followup[0]))

如果不使用 previous_response_id，而是自行管理 conversation state，请将上一 turn 的 output item（包括 image_generation_call item）通过 input 原样传回；这些 item 携带的图像在下一个请求中仍可编辑。

与其他 Tool 结合

Image generation tool 可以与其他 server-side tool 组合。在同一请求中包含多个 tool，model 会在单个 agentic loop 中协调它们，将一个 tool 的发现传给下一个。以下示例先通过 web search 查找事实，再根据获取的信息编写 image prompt：

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.5",
  "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.",
  "tools": [
    {
      "type": "web_search"
    },
    {
      "type": "image_generation"
    }
  ]
}' | jq -r '.output[] | select(.type == "image_generation_call") | .result' \
  | base64 --decode > champions_poster.jpg

import base64
import os

from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.5",
    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."
    ),
    tools=[
        {"type": "web_search"},
        {"type": "image_generation"},
    ],
)

for output in response.output:
    if output.type == "web_search_call":
        print(f"Web search: {output.action}")
    elif output.type == "image_generation_call":
        print(f"Image prompt: {output.prompt}")
        with open("champions_poster.jpg", "wb") as f:
            f.write(base64.b64decode(output.result))
    elif output.type == "message":
        print(output.content[0].text)

Response output 按执行顺序交错包含 tool call：一个 web_search_call item、一条带 citation 回答事实问题的 message，以及一个携带海报的 image_generation_call item。

相同模式也适用于 X search、code execution 和自己的 client-side function。更多 tool 组合模式请参阅高级用法。

Streaming

Streaming 时，每次 image generation call 都会发出进度 event：in_progress，然后是 generating，然后是 completed；之后发出 response.output_item.done event，其 item 携带 base64 result。不会发出 partial image preview。

import base64
import os

from openai import OpenAI

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

stream = client.responses.create(
    model="grok-4.5",
    input="Generate an image of an origami fox in a paper forest",
    tools=[{"type": "image_generation"}],
    stream=True,
)

for event in stream:
    if event.type.startswith("response.image_generation_call."):
        # in_progress -> generating -> completed
        print(f"Image generation status: {event.type.rsplit('.', 1)[-1]}")
    elif event.type == "response.output_item.done" and event.item.type == "image_generation_call":
        # The base64 image rides on the final output item
        with open("origami_fox.jpg", "wb") as f:
            f.write(base64.b64decode(event.item.result))
    elif event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const stream = await client.responses.create({
  model: "grok-4.5",
  input: "Generate an image of an origami fox in a paper forest",
  tools: [{ type: "image_generation" }],
  stream: true,
});

for await (const event of stream) {
  if (event.type.startsWith("response.image_generation_call.")) {
    // in_progress -> generating -> completed
    console.log(`Image generation status: ${event.type.split(".").pop()}`);
  } else if (
    event.type === "response.output_item.done" &&
    event.item.type === "image_generation_call"
  ) {
    // The base64 image rides on the final output item
    fs.writeFileSync(
      "origami_fox.jpg",
      Buffer.from(event.item.result, "base64")
    );
  } else if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

Image Generation，使用 images endpoint 直接生成图像
Image Editing，使用自然语言编辑图像
Tool 概览，所有 built-in tool
Streaming 与同步，启用 tool 的请求的 streaming 行为
定价，tool invocation 费用

工具

Image Generation Tool