Set resolution on Imagine API images

Pin 1k or 2k when you generate a still through the Imagine API so the output matches the sharpness you need for print, a hero, or a quick draft. Official Image Generation documents the resolution parameter on image generation. When you omit it, the default is 1k. Model id for current Quality Mode parity is grok-imagine-image-2.0. Create a key and load credits at console.x.ai before you bill a 2k run.

What you need

An XAI_API_KEY with Console balance, a concrete prompt (subject, verb, light, what stays out of frame), and a decision on whether this placement needs the higher resolution. Consumer Smart resize and Quality Mode on grok.com are a different path — Smart-resize an image in Grok Imagine — use this API job when you want resolution on the first generation from a prompt.

Generate at 2k

1. Export the key locally and keep it out of chat logs and public repos:

export XAI_API_KEY="your_api_key"

2. Call the generations endpoint with resolution set to 2k (example):

curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "An astronaut performing EVA in LEO, sharp helmet reflections, clear Earth limb",
    "resolution": "2k"
  }'

3. Or use the xAI Python SDK:

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.image.sample(
    prompt="An astronaut performing EVA in LEO, sharp helmet reflections, clear Earth limb",
    model="grok-imagine-image-2.0",
    resolution="2k",
)

print(response.url)

4. Download the temporary URL promptly, then check whether fine detail (type, edges, fabric) holds at the size you will publish.
5. Combine with aspect_ratio when the channel frame is already fixed — Set aspect ratio on Imagine API images — and with quality when you intentionally pin billing quality — Set quality on grok-imagine-image-2.0.

OpenAI-compatible clients often pass resolution through extra_body={"resolution": "2k"} because the stock helper may not expose the field. The Vercel AI SDK maps it under providerOptions.xai.resolution.

After the generate

If the resolution is right but a region is wrong, edit from the output URL with Edit an image with the Imagine API. When you need several candidates at the same resolution, raise n in one request — Generate image variations with the Imagine API — instead of firing separate 2k calls you will never open. First-time API setup still starts at Send your first Grok API request for key hygiene.

Pitfalls

Omitting resolution when the placement needs print or large-hero sharpness leaves you on the 1k default. Upscaling a soft 1k still in an external editor after the fact wastes the model’s native 2k path. Pasting keys into tickets or committing them to git forces a rotate. Mixing Console API spend with SuperGrok weekly Imagine quotas on grok.com confuses two different meters. Letting temporary URLs expire before download loses the only copy of a paid generation.