xAI Grok Imagine Image API Guide: Aspect Ratio & b64_json

Mastering Visual Creation with the xAI Grok Imagine API: Aspect Ratios, Base64 Payloads, and Beyond

The evolution of generative artificial intelligence has shifted the focus from merely creating pixels to ensuring precise programmatic control over layout, quality, and data delivery. Within xAI’s developer ecosystem, the Grok Imagine Image model family—anchored by grok-imagine-image-2.0—provides powerful OpenAI-compatible endpoints that allow developers to generate and edit images seamlessly.

When configuring production pipelines using site:docs.x.ai/developers/model-capabilities/images/generation parameters, mastering layout specifications via aspect_ratio, payload formatting via b64_json, and model selection under grok-imagine-image is essential for high-performance applications.

Core Architecture and Model Tiering

The Grok Imagine suite handles text-to-image generation and multi-reference image editing through unified endpoints. The current flagship model, grok-imagine-image-2.0, replaces earlier iterations by supporting an expanded matrix of aspect ratios, advanced quality tiers (low, medium, and auto), and flexible multi-image reference inputs.

When constructing requests, developers interact with standard parameters designed to mirror common developer expectations while optimizing for xAI’s native generation stack:

• model: Specifies the target engine, such as grok-imagine-image-2.0.
• prompt: The textual description detailing the style, subject, and composition.
• n: The number of images to generate in a single batch (typically ranging from 1 to 10).

Controlling Composition: The aspect_ratio Parameter

One of the most critical aspects of automated asset generation is layout consistency. Hard-cropping final images introduces latency and risks clipping essential elements. The xAI image API eliminates this friction by offering deep control over canvas dimensions via the aspect_ratio parameter.

Instead of raw pixel-height and width declarations that can confuse underlying diffusion architectures, grok-imagine-image-2.0 accepts a broad suite of 15 fixed aspect ratios alongside an auto setting:

• Landscape Options: 16:9, 4:3, 3:2, 2:1, 19.5:9, 20:9, 21:9, and 5:2
• Portrait Options: 9:16, 3:4, 2:3, 1:2, 9:19.5, and 9:20
• Square: 1:1
• Flexible: auto (lets the model dictate composition based on the text prompt)

If the aspect_ratio parameter is omitted entirely, the model defaults to a standard layout configuration depending on the context, but passing an explicit ratio ensures predictable UI integration—such as pairing 16:9 for cinematic headers or 9:16 for mobile stories.

Streamlining Data Flow with b64_json

By default, image generation APIs often return temporary web URLs pointing to cloud storage buckets. While convenient for quick tests, URLs introduce external dependencies, expiration timeframes, and security considerations if links leak or break.