Grok Imagine

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, Image Editing, Multi-Image Editing, and the Images REST API.

Anything outside these enums returns 422, and OpenAI-only fields (size, style, background, output_format, quality:"hd") return 400 or are silently ignored. Don't reach for them.