/grok-imagine

name: grok-imagine
version: 3.0.0
description: |
  Generate or edit images via Grok Imagine Image 2.0 through DroidProxy
  (no XAI_API_KEY). Use when the user asks to generate, create, draw,
  imagine, or edit an image, illustration, icon, mockup, or similar
  visual asset and DroidProxy Grok OAuth is available. Prefer this over
  inventing image URLs or base64.

Grok Imagine Image 2.0 (via DroidProxy)

Generate and edit images with **`grok-imagine-image-2.0`** using the SuperGrok / X Premium+ OAuth session that powers DroidProxy chat. This is the current Imagine image model (text or image → image). Do not use the older `grok-imagine-image` / `grok-imagine-image-quality` ids unless the user explicitly asks for them.

Two things you can't guess and that everything else depends on:

• The endpoint is **`http://localhost:8317`**, not `api.x.ai`. DroidProxy

TLS-forwards any request whose `model` starts with `grok-` and injects the OAuth bearer.

• Auth is **`Authorization: Bearer dummy-not-used`**. The real token comes from

the proxy. Never ask for or use an `XAI_API_KEY`.

Use for generating or editing visual assets. Not for understanding an image the user already attached — that's chat multimodal, not this skill.

Prompting

xAI rewrites the prompt with an upsampler before generation, so write a clear scene rather than a tag soup. If the user gives a detailed prompt or asks you to use theirs, use it verbatim. Otherwise craft 2–5 sentences of natural prose:

**subject → action/pose → setting → style → composition → lighting/mood → key details**

• Front-load the subject. Give strong high-level direction for mood,

composition, lighting, and style without specifying every pixel.

• State what to include, not what to exclude. No negative prompts.
• One coherent scene per prompt. Match `aspect_ratio` to the use case:

icons `1:1`, banners `16:9`, stories `9:16`.

• For **edits**, describe only what changes and what must stay the same.
• For **multi-image edits**, address sources as `<IMAGE_0>`, `<IMAGE_1>`,

`<IMAGE_2>` in the prompt (max 3). Combining subjects, transferring a style, or composing a scene from references is the intended use.

• Ground real people, brands, places, and “current/latest” facts with a web

search first and put the verified details in the prompt. For a named real person, edit from a real reference photo — do not generate the likeness from text alone.

Generate

RESP=$(curl -sS http://localhost:8317/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dummy-not-used" \
  -d "$(jq -n --arg p "A red balloon on a wooden table, soft natural light" \
    '{model:"grok-imagine-image-2.0", prompt:$p, aspect_ratio:"1:1",
      resolution:"1k", response_format:"b64_json"}')")

if B64=$(printf '%s' "$RESP" | jq -er '.data[0].b64_json' 2>/dev/null); then
  printf '%s' "$B64" | base64 -d > out.jpg
else
  printf '%s\n' "$RESP" >&2   # errors are plain text, not JSON
  exit 1
fi

Two things that bite here:

• **Check `.data[0].b64_json` before decoding.** On failure there is no b64

field, and piping the error body through `base64 -d` writes a corrupt file that passes an `ls` check and only reveals itself when someone opens it.

• **Print the raw body on failure, not `jq '.error.message'`.** Errors come

back as `text/plain`, so parsing them as JSON discards the useful part. The raw text is specific and worth reading — a bad `aspect_ratio` replies ``unknown variant `21:9`, expected one of `1:1`, `3:4`, ...``, which tells you exactly what to send.

Edit

`POST /v1/images/edits`, same auth and routing. Pass **either** `image` (single) or `images` (up to 3 references, addressed as `<IMAGE_0>`, `<IMAGE_1>`, `<IMAGE_2>` in the prompt) — never both. Each source is JPEG, PNG, or WebP.

curl -sS http://localhost:8317/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dummy-not-used" \
  -d "$(jq -n --arg p "Make it blue-tinted studio lighting" --arg u "$SRC" \
    '{model:"grok-imagine-image-2.0", prompt:$p,
      image:{url:$u, type:"image_url"},
      response_format:"b64_json"}')"

The source `url` takes a public HTTPS URL, an xAI `file_id` (on the image object, mutually exclusive with `url`), or a data URL. For a **local file** there's no upload step — inline it as a data URL:

SRC="data:image/jpeg;base64,$(base64 -i ./photo.jpg)"

Omit `aspect_ratio` on single-image edits; it follows the source, and setting it can crop or letterbox. On multi-image edits it follows the first source unless you override it.

Chain edits by feeding each output back as the next `image`. That is how you refine, restyle, or correct without starting over.

Parameters

Source of truth: [Image Generation](https://docs.x.ai/developers/model-capabilities/images/generation), [Image Editing](https://docs.x.ai/developers/model-capabilities/images/editing), [Multi-Image Editing](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing), and the [Images REST API](https://docs.x.ai/developers/rest-api-reference/inference/images).

| Field | Values | Notes | |---|---|---| | `model` | `grok-imagine-image-2.0` | Must start with `grok-` or the proxy won't route it. Always send this id. | | `prompt` | string | See Prompting. Required on edits. | | `aspect_ratio` | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `9:19.5`, `19.5:9`, `9:20`, `20:9`, `1:2`, `2:1`, `auto` | Default `auto` (model picks the ratio). Icons `1:1`, banners `16:9`, stories `9:16`. | | `resolution` | `1k`, `2k` | Default `1k`. Stay there unless the user asks for print/hi-dpi — `2k` returns much larger files. | | `quality` | `low`, `medium` | **2.0 only.** Default `medium` when omitted. Do not send `high`, `hd`, or `standard`. Omit unless the user asks for `low`. | | `response_format` | `url`, `b64_json` | `url` is the default but expires fast — prefer `b64_json` when saving to disk.