Set aspect ratio on Imagine API images

Pin the frame size when you generate a still through the Imagine API so the output matches the placement you already planned (Story, slide, banner, thumbnail). Official Image Generation documents the aspect_ratio parameter on image generation. When you omit it, the default is auto, which lets the model pick a ratio for the prompt. Model id for current Quality Mode parity is grok-imagine-image-2.0. Get a key and credits at console.x.ai.

What you need

An XAI_API_KEY with Console balance, a prompt that states the scene clearly, and the target ratio for the channel you are shipping to. Consumer Smart resize on an existing still is a different path — Smart-resize an image in Grok Imagine — use this API job when you want the ratio on the first generation.

Supported ratios

Pass one of the documented values:

Ratio	Typical placement
1:1	Social thumbnails
16:9 / 9:16	Widescreen, mobile stories
4:3 / 3:4	Presentations, portraits
3:2 / 2:3	Photography
2:1 / 1:2	Banners, headers
19.5:9 / 9:19.5	Modern smartphone displays (iPhone)
20:9 / 9:20	Modern smartphone displays (Android)
21:9	Cinematic widescreen
5:2	Wide banners
auto	Model chooses for the prompt

Generate at a fixed ratio

1. Export the key:

export XAI_API_KEY="your_api_key"

2. Call generations with aspect_ratio set (example locks 16:9):

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": "Mountain landscape at sunrise, sharp ridgeline, clear sky",
    "aspect_ratio": "16:9"
  }'

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="Mountain landscape at sunrise, sharp ridgeline, clear sky",
    model="grok-imagine-image-2.0",
    aspect_ratio="16:9",
)

print(response.url)

4. Download the temporary URL promptly, then review whether the composition still holds at that frame.
5. Combine with n when you want several candidates at the same ratio — Generate image variations with the Imagine API — and keep quality / resolution only when you intentionally pin those Image 2.0 controls from the same docs page.

OpenAI SDK users often pass aspect ratio through extra_body={"aspect_ratio": "16:9"} because the stock helper may not expose the field directly. The Vercel AI SDK maps it as aspectRatio.

After the generate

If the ratio is right but a region is wrong, edit from the output URL with Edit an image with the Imagine API. If you already have an approved consumer still and only need a new frame, prefer Smart resize on grok.com instead of regenerating from scratch. First-time API setup still starts at Send your first Grok API request for key hygiene.

Pitfalls

Omitting aspect_ratio when the channel is fixed leaves you with auto crops you did not plan. Stretching a still in an external editor after a wrong ratio wastes the model’s frame-aware generation. 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.