Grok Imagine API 是 xAI 的图像生成与编辑 API，面向需要在代码中集成图像生成、编辑与细化能力的开发者。
主要能力 支持文生图、基于 JSON 的图像编辑、多图编辑、多轮细化、批量变体、宽高比控制、1k/2k 分辨率、URL 输出和 base64 输出。单次请求最多支持 10 张图像；图像编辑最多支持 5 张输入图像。
接入方式
- xai_sdk：适合 Python 及使用第一方功能的场景，使用 client.image.sample() 和 sample_batch()。
- REST：适合任意语言、需要完全控制的场景，向 /images/generations 或 /images/edits 发送 JSON。
- OpenAI SDK：适合作为即插即用的图像生成方案，将 base_url / baseURL 指向 https://api.x.ai/v1。
- Vercel AI SDK：适合已使用 AI SDK 的 TypeScript 应用，使用 xai.image("grok-imagine-image") 配合 generateImage()。
注意：OpenAI SDK 的 images.edit() 不支持 Grok Imagine 编辑，因为它发送 multipart/form-data，而 xAI 图像编辑要求 application/json。
快速开始
原生 REST：
curl -X POST https://api.x.ai/v1/images/generations
-H "Content-Type: application/json"
-H "Authorization: Bearer $XAI_API_KEY"
-d '{
"model": "grok-imagine-image",
"prompt": "A collage of London landmarks in a stenciled street-art style"
}'
Python xAI SDK： import xai_sdk
client = xai_sdk.Client() response = client.image.sample( model="grok-imagine-image", prompt="A collage of London landmarks in a stenciled street-art style", ) print(response.url)
OpenAI 兼容生成： from openai import OpenAI
client = OpenAI(base_url="https://api.x.ai/v1", api_key="YOUR_API_KEY") response = client.images.generate( model="grok-imagine-image", prompt="A collage of London landmarks in a stenciled street-art style", ) print(response.data[0].url)
核心工作流
- 选择生成还是编辑：新图像使用 POST /v1/images/generations、client.image.sample() 或 images.generate()；编辑图像使用 POST /v1/images/edits、xAI SDK 的 sample(image_url=...) 或 Vercel AI SDK 的 provider options。
- 设置模型、提示词，以及可选的 n、aspect_ratio、resolution 或输出格式。
- 图像编辑时传入公开图像 URL 或 base64 data URI，最多支持 5 张输入图像。
- 生成的 URL 视为临时地址，应及时下载；若需直接嵌入或保存，可请求 base64 输出。
- 使用 xai_sdk 时检查审核元数据，不要假设每次请求都会产生可用图像。
常见模式
- 同一提示词生成多个变体：使用 sample_batch(..., n=...) 或 images.generate(..., n=...)。
- 并行使用不同提示词：使用 xai_sdk.AsyncClient() 配合 asyncio.gather()。
- 单图编辑：输出宽高比跟随输入图像。
- 多图编辑：除非设置 aspect_ratio，否则输出宽高比跟随第一张输入图像。
- base64 输出：xAI SDK 使用 image_format="base64"；OpenAI 兼容 SDK 使用 response_format="b64_json"。
- 分辨率取值：1k 或 2k。
- 单次请求最大图像数：10。
模型与定价 应使用官方 xAI 文档确认当前确切的模型可用性与定价。不要推荐已弃用的 grok-imagine-image-pro；将现有用法迁移到 grok-imagine-image-quality 或当前文档记载的 Grok Imagine 图像模型。
参考 端点结构、各 SDK 的参数名称、编辑负载、宽高比、响应处理和故障排查，参见 references/image-api.md。