nikships/droidproxy/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.

Response

{"data": [{"b64_json": "...", "mime_type": "image/jpeg", "url": "https://imgen.x.ai/..."}]}

Pick the file extension from mime_type, not from the prompt or the filename the user asked for — 1k usually returns JPEG and 2k often returns PNG, so a .jpg name on PNG bytes is a real outcome. If that contradicts the name they gave, save the correct extension and say why. mime_type may also be image/webp.

With response_format: "url" the URL is temporary (imgen.x.ai) — download it immediately rather than handing it to the user.

No transparency

Imagine has no alpha channel; output is always opaque JPEG, PNG, or WebP. There is no API field that changes this, so don't send one.

When someone asks for a transparent PNG:

1. Generate on a flat, uniform background that contrasts with the subject.
2. Key it out locally (PIL, ImageMagick).
3. Recolor the subject for the background they named, before you finish.

Someone asking for transparency has told you where it's going — "over our dark header," "on a white card." Keying preserves whatever ink Imagine happened to render, which is usually near-black, so a mark destined for a dark background comes out invisible. Compare the subject's luminance to the target background and invert it if they collide. That's the difference between a usable asset and one the user has to send back.

1. Say what you did, and mention the ink color you chose so they can ask for

the other one.

Failures

Most errors explain themselves; these three don't:

On a moderation / safety block, stop. Don't retry and don't paraphrase the prompt to evade the filter. Tell the user it was blocked and offer a different direction.

Report the API's own message rather than guessing, and never invent image content or a URL for a request that failed.