Grok CLI Manual

图片生成与编辑

Grok 的图片工具使用独立的 xai_api_base_url；只配置 models_base_url 不会让 image_gen 经过 XAI Router。

配置图片端点

在 ~/.grok/config.toml 中同时配置模型与图片入口：

[models]
default = "grok-4.5"

[endpoints]
models_base_url = "https://api.xairouter.com"
xai_api_base_url = "https://api.xairouter.com"

[model."grok-4.5"]
model = "grok-4.5"
api_key = "YOUR_XAI_ROUTER_KEY"
api_backend = "responses"

[auth]
preferred_method = "api_key"

models_base_url 用于模型列表与主要推理请求；image_gen 和 image_edit 单独读取 xai_api_base_url。两项统一填写同一个不带 /v1 的 XAI Router 主 API 域名。两条链路使用同一个用户 Key，不要把 Grok OAuth refresh_token 填入配置。preferred_method = "api_key" 可防止已有 OAuth 会话在工具请求时覆盖 Router Key。直接调用 API 时仍按标准路径使用 /v1/images/...。

在 Grok CLI 中生成图片

交互界面可以直接使用 /imagine：

/imagine 一只戴宇航员头盔的橘猫，电影感光线，1:1 构图

也可以在自然语言任务中明确要求调用工具：

请立即调用 image_gen，生成一张 16:9 的未来城市夜景，不要改写我的提示词。

成功后，Grok 会把结果保存到当前会话的 images/<编号>.jpg，并在回复中给出可点击路径。

直接调用图片生成 API

curl --fail-with-body -sS https://api.xairouter.com/v1/images/generations \
  -H 'Authorization: Bearer YOUR_XAI_ROUTER_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "一只戴宇航员头盔的橘猫，电影感光线",
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "b64_json"
  }' > grok-image-response.json

jq -er '.data[0].b64_json' grok-image-response.json \
  | base64 --decode > grok-image.jpg

macOS 自带的 base64 使用 -D 代替 --decode。

在 Grok CLI 中编辑图片

给出本地图片的绝对路径或附加图片，并明确要求使用 image_edit：

请调用 image_edit 编辑 /absolute/path/to/reference.jpg：保留主体与构图，把背景改成雨夜霓虹街道。

Grok CLI 会读取并压缩参考图，然后以 data URL 调用图片编辑端点。

直接调用图片编辑 API

单张参考图使用 image 对象。下面的命令会把 reference.jpg 转成 data URL：

REFERENCE_B64="$(base64 < reference.jpg | tr -d '\r\n')"

curl --fail-with-body -sS https://api.xairouter.com/v1/images/edits \
  -H 'Authorization: Bearer YOUR_XAI_ROUTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON > grok-edit-response.json
{
  "model": "grok-imagine-image-quality",
  "prompt": "保留主体与构图，把背景改成雨夜霓虹街道",
  "n": 1,
  "resolution": "1k",
  "response_format": "b64_json",
  "image": {
    "url": "data:image/jpeg;base64,${REFERENCE_B64}"
  }
}
JSON

jq -er '.data[0].b64_json' grok-edit-response.json \
  | base64 --decode > grok-edited.jpg

多张参考图改用 images 数组，并显式提供输出比例：

{
  "model": "grok-imagine-image-quality",
  "prompt": "融合两张参考图的主体与风格",
  "n": 1,
  "resolution": "1k",
  "response_format": "b64_json",
  "images": [
    { "url": "data:image/jpeg;base64,<第一张图片>" },
    { "url": "data:image/png;base64,<第二张图片>" }
  ],
  "aspect_ratio": "16:9"
}

常用字段

排查要点

• Router Key 报 Incorrect API key provided：通常是漏配 xai_api_base_url，请求仍直达 api.x.ai。
• 环境中已有 XAI_API_KEY：图片工具在 API Key 模式下会优先读取它，而不是模型块里的 api_key；请把它设为同一个 Router Key，或执行 unset XAI_API_KEY GROK_CODE_XAI_API_KEY 清除新旧变量后重启 Grok CLI。
• 模型不可用：确认当前 Key 可以使用 grok-imagine-image-quality。
• 401、403 或 429：检查 Key、上游账号的 Imagine 权限与额度。
• 本页只覆盖图片生成与编辑，不代表视频生成链路已经开放。

模型能力以 xAI Grok Imagine Image Quality 模型页 为准。