Grok CLI Manual

Image Generation and Editing

Grok image tools use a separate xai_api_base_url; configuring models_base_url alone does not route image_gen through XAI Router.

Configure the image endpoint

Set both the model and image endpoints in ~/.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 handles model discovery and primary inference requests. image_gen and image_edit read xai_api_base_url separately. Set both to the same XAI Router main API origin without /v1. Both paths use the same user Key; do not put a Grok OAuth refresh_token in this configuration. preferred_method = "api_key" prevents an existing OAuth session from replacing the Router Key on tool requests. Direct API calls still use the standard /v1/images/... paths.

Generate an image in Grok CLI

Use /imagine in the interactive UI:

/imagine An orange cat wearing an astronaut helmet, cinematic lighting, 1:1 composition

You can also explicitly request the tool in a normal task:

Call image_gen immediately and create a 16:9 futuristic city at night. Do not rewrite my prompt.

On success, Grok stores the result under the current session's images/<number>.jpg path and links it in the reply.

Call the image generation API directly

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": "An orange cat wearing an astronaut helmet, cinematic lighting",
    "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

The built-in macOS base64 command uses -D instead of --decode.

Edit an image in Grok CLI

Provide an absolute local image path or attach an image, then explicitly request image_edit:

Call image_edit on /absolute/path/to/reference.jpg. Preserve the subject and composition, but replace the background with a neon street in the rain.

Grok CLI reads and compresses the reference before sending it to the image edit endpoint as a data URL.

Call the image edit API directly

Use an image object for one reference. This example converts reference.jpg into a 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": "Preserve the subject and composition, but replace the background with a neon street in the rain",
  "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

For multiple references, use an images array and provide the output aspect ratio explicitly:

{
  "model": "grok-imagine-image-quality",
  "prompt": "Combine the subjects and styles of both references",
  "n": 1,
  "resolution": "1k",
  "response_format": "b64_json",
  "images": [
    { "url": "data:image/jpeg;base64,<FIRST_IMAGE>" },
    { "url": "data:image/png;base64,<SECOND_IMAGE>" }
  ],
  "aspect_ratio": "16:9"
}

Common fields

Troubleshooting

• Router Key returns Incorrect API key provided: xai_api_base_url is usually missing, so the request still goes directly to api.x.ai.
• XAI_API_KEY already exists in the environment: image tools read it before the model block's api_key in API Key mode. Set it to the same Router Key, or run unset XAI_API_KEY GROK_CODE_XAI_API_KEY to clear both current and legacy variables, then restart Grok CLI.
• The model is unavailable: confirm that the current Key can use grok-imagine-image-quality.
• 401, 403, or 429: check the Key and the upstream account's Imagine permission and quota.
• This page covers image generation and editing only; it does not imply that the video pipeline is enabled.

See the xAI Grok Imagine Image Quality model page for current model capabilities.