Aspect Ratios, Resolutions, and Output Formats

Updated November 2, 2026 — Imagine. grok-imagine-image-quality has been removed as of November 2, 2026 (its requests are served by Imagine 2.0 in low quality): examples now use grok-imagine-image (Imagine 1.0) and grok-imagine-image-2.0 (Imagine 2.0, low, medium, or auto quality). With the OpenAI SDK, aspect_ratio, resolution, and quality pass via extra_body, and editing goes through the xAI SDK or an HTTP request.

Mastering Your Image Dimensions

The aspect ratio and resolution you choose directly determine the appearance and use of your generated images. The Grok Imagine API offers significant flexibility with numerous predefined ratios and two resolution levels.

Available Aspect Ratios

Choose the ratio based on the destination, and choose it before generating. Cropping a square image into a panoramic banner after the fact cuts into the composition the model built for a square: the subject ends up off-center, margins disappear. Generating directly in the right format costs the same and gives you an image designed for its proportions.

Additional ratios are also available for specific cases like smartphone screens: 9:19.5, 19.5:9, 9:20, and 20:9.

Resolutions: 1k vs 2k

Between 1k and 2k, the question isn’t “which is best” but “where will this image be viewed”. On a screen, the difference is invisible for the vast majority of web uses, and 2k only costs extra generation time. It becomes critical for print, however, where the number of pixels per centimeter directly determines perceived sharpness.

• 1k: Standard resolution, suited for most web uses. Faster generation time.
• 2k: High resolution, ideal for print or visuals requiring lots of detail.

# Standard resolution for web
response_web = client.images.generate(
    model="grok-imagine-image",
    prompt="Neon-style mobile app icon",
    extra_body={"resolution": "1k", "aspect_ratio": "1:1"},
)

# High resolution for print
response_print = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="Art deco concert poster with elegant typography",
    extra_body={"resolution": "2k", "aspect_ratio": "3:4"},
)

Response Formats

The response_format parameter determines how the image is returned to you:

Temporary URL (Default)

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Astronaut cat",
    response_format="url"
)
# response.data[0].url → Temporary URL, download quickly

Base64 JSON

import base64

response = client.images.generate(
    model="grok-imagine-image",
    prompt="Astronaut cat",
    response_format="b64_json"
)

image_bytes = base64.b64decode(response.data[0].b64_json)
with open("astronaut_cat.png", "wb") as f:
    f.write(image_bytes)

The important word is temporary: the returned URL expires. An application that stores it in a database and displays it weeks later will encounter broken images, often well after deployment. Two options work: download the image from the URL immediately, or request Base64 directly—in either case, the image must end up on your own storage.

Choosing the Right Combination

For each use case, here are the recommended combinations:

• Instagram Post: 1:1, resolution 1k, Imagine 1.0
• Story/Reel: 9:16, resolution 1k, Imagine 1.0
• Web Banner: 16:9 or 2:1, resolution 1k, Imagine 1.0
• Event Poster: 3:4, resolution 2k, Imagine 2.0 in medium quality
• Article Illustration: 16:9, resolution 2k, Imagine 2.0 in medium quality

Key Takeaways

• Over 10 aspect ratios available, plus auto mode
• Two resolutions: 1k (fast, web) and 2k (detailed, print)
• Two response formats: url (temporary) and b64_json (persistent)
• Returned MIME types can be PNG, JPEG, or WebP
• Adapt the ratio to your image’s distribution channel