grok-imagine-api

Grok Imagine API

Grok Imagine 是 xAI 的图像生成与编辑 API。它支持文本生成图像、基于 JSON 的图像编辑、多图编辑、多轮优化、批量生成变体、宽高比控制、1k/2k 分辨率、URL 输出和 base64 输出。

需要了解当前确切的模型可用性和定价时，请参阅 xAI 官方文档。请勿推荐已弃用的 grok-imagine-image-pro；请将现有用法迁移到 grok-imagine-image-quality 或当前文档列出的 Grok Imagine 图像模型。

快速开始

原始 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)

集成方式

方式	最适合	说明
xai_sdk	Python、一方功能	使用 client.image.sample() 和 sample_batch()。
REST	任意语言、完全控制	将 JSON 发送到 /images/generations 或 /images/edits。
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。

核心工作流

1. 选择生成或编辑：
   • 新图像：POST /v1/images/generations、client.image.sample() 或 images.generate()。
   • 编辑图像：POST /v1/images/edits、xAI SDK 的 sample(image_url=...) 或 Vercel AI SDK 提供程序选项。
2. 设置 model、prompt，以及可选的 n、aspect_ratio、resolution 或输出格式。
3. 编辑图像时，传入公开图像 URL 或 base64 数据 URI。最多支持 5 张输入图像。
4. 生成的 URL 是临时的。请及时下载，或在需要直接嵌入/保存时请求 base64 输出。
5. 使用 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。

参考

请参阅 references/image-api.md，了解端点格式、各 SDK 的参数名称、编辑请求负载、宽高比、响应处理和故障排查。