Grok Imagine 图片 API 入门：用 curl 和 Python 生成首张图

调用 Grok Imagine 图片 API，需要向 xAI 图片生成接口提交 prompt 和模型 ID，再保存返回的图片。 先只生成一张并显式指定配置，确认响应后再扩展批量任务或编辑流程。

本文使用 grok-imagine-image-2.0，依据 2026 年 9 月 8 日核对的官方生成文档。示例没有执行付费生成，不构成延迟、画质或费用实测。需要有对应权限的 xAI key、服务端运行环境和图片存储。核对时 Ofox 目录尚未收录 Grok Imagine，Ofox key 不能用于 xAI 直连。

用 curl 发起单张请求

通过现有密钥管理方式设置 XAI_API_KEY，在终端或后端执行。实际执行会产生 API 用量费用，不要把 key 写进公开的浏览器代码。

curl --fail-with-body --silent --show-error \
  --max-time 180 \
  https://api.x.ai/v1/images/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Studio photograph of a matte blue ceramic cup on a pale stone shelf, soft light from the left, no lettering",
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "url"
  }' \
  -o grok-image-response.json

prompt 是示例创作要求，不是测试后选出的最佳提示词。180 秒超时是客户端设置，不是服务商速度承诺。先检查命令退出状态与保存的 JSON，确认不是错误对象，再下载图片。保留完整响应比直接把假定存在的 URL 传给下载器更便于定位问题。

用 Python 保存返回图片

先在项目环境中安装 requests。下面直接发送 HTTP 请求，选择 base64 响应，检查图片数据并保存原始字节。

import base64
import os
from pathlib import Path

import requests

payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": (
        "Studio photograph of a matte blue ceramic cup on a pale "
        "stone shelf, soft light from the left, no lettering"
    ),
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "b64_json",
}
response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    json=payload,
    timeout=(10, 180),
)
response.raise_for_status()
body = response.json()
images = body.get("data", [])
if not images or not images[0].get("b64_json"):
    raise RuntimeError("No base64 image returned; inspect response metadata")
image_bytes = base64.b64decode(images[0]["b64_json"], validate=True)
# Keep raw bytes until your image decoder identifies the returned format.
output = Path("grok-image-output.bin")
output.write_bytes(image_bytes)
print(f"Saved {len(image_bytes)} bytes to {output}")

.bin 扩展名是有意使用的：尚未解码就命名为 PNG 或 JPEG，会把未经确认的格式写成事实。业务中应通过图片解码器核对格式、尺寸，再选择正确扩展名与媒体类型。

接口也支持 URL 响应，但返回地址是临时的；需要长期保存的素材应及时存入自己的存储。见响应格式说明。

批量生成前，固定哪些参数？

将目标宽高比、预算画质和输出数量写入任务规格，随后再扩展后台任务。每次生成至少记录：

生成与编辑应分开设计。编辑包含输入图，需采用对应请求结构并另算预算。不要给生成请求随意加一个 image 字段，就假定所有服务商都能识别。应查官方编辑文档。

重试前先判断失败位置

连接失败、HTTP 错误、成功响应里出现意外内容，应走不同排查路径。鉴权失败时检查目标域名与 key 来源；参数校验失败时先缩小请求，再对照接口字段。

提交后网络超时，不代表服务端一定没有完成生成。没有确认结果前，不要自动重复付费请求。后台任务应保存响应元数据，并明确什么时候允许重新提交；日志不要记录 Authorization 头。

若结果与审核规则有关，先查看文档说明，调整请求使其符合服务规则。无限重试不能让不受支持的请求变得受支持。更一般的排查可参考图片生成失败指南，具体参数仍以当前调用的服务为准。

接进现有应用

将服务商特有的请求字段集中在适配层。业务侧描述提示词、参考素材和输出形状，再由适配层校验和转换。这样换服务商时，可以保留同一创作要求，不必在整套业务里散落模型专属字段。

可结合 FLUX 接入流程考虑适配边界。扩大用量前先看 Image 2.0 价格与预算；迁移旧别名时看 quality 型号迁移。