xAI Grok Image Generation API: Aspect Ratio & Base64 Guide

xAI’s suite of media capabilities has evolved rapidly, and at the heart of programmatic visual synthesis lies the Grok Imagine Image ecosystem. When building applications that require high-performance visual generation, developers look closely at xAI’s API endpoints (docs.x.ai) to orchestrate parameters like aspect_ratio, response payloads such as b64_json, and the flagship model series like grok-imagine-image-2.0.

Unlocking the full potential of these parameters allows engineers to transition from basic prototyping to scalable, production-ready media pipelines.

The Engine: grok-imagine-image-2.0

At the core of xAI’s latest image generation infrastructure is grok-imagine-image-2.0. Succeeding earlier iterations, this model is built for dense detail rendering, precise adherence to multi-reference compositions, and flexible layout handling.

When configuring API calls against xAI’s OpenAI-compatible image endpoints, specifying the model correctly ensures access to the latest feature sets, including expanded aspect ratio presets and refined quality layers.

Direct Control Over Layout with aspect_ratio

One of the most frequent constraints in production application design is matching UI containers and design systems. In standard implementations, omitting parameters or setting them to auto lets the model decide the composition frame. However, xAI’s API gives developers explicit control via the aspect_ratio parameter.

The grok-imagine-image-2.0 architecture supports a granular set of 15 fixed aspect ratios, spanning standard squares, cinematic landscapes, and vertical mobile formats:

• Square: 1:1
• Landscape: 16:9, 4:3, 3:2, 2:1, 19.5:9, 20:9, 21:9, 5:2
• Portrait: 9:16, 3:4, 2:3, 1:2, 9:19.5, 9:20

By passing a targeted ratio (such as aspect_ratio="16:9" for video banners or aspect_ratio="9:16" for mobile stories), you bypass the guesswork and guarantee that downstream components ingest assets matching exact spatial requirements. Furthermore, combining these ratios with resolution flags like resolution="1k" or resolution="2k" tunes the balance between generation speed and asset sharpness.

Handling Payloads with b64_json

When managing media retrieval in enterprise or security-sensitive workflows, dealing with temporary external URLs can introduce friction or data lifecycle management overhead. To bypass temporary URLs, xAI’s API supports setting the response_format parameter to b64_json.

When b64_json is requested:

• The API returns the generated image payload encoded as a base64 string directly inside the JSON response body (data[].b64_json).
• The returned string comes without a data-URL prefix (meaning no data:image/jpeg;base64, header wrapper), requiring a straightforward decoder implementation on the client or server side.
• This pattern is ideal for microservices that need to pipe image bytes straight into object storage (like AWS S3 or Google Cloud Storage), pass assets safely across internal message queues, or render instant previews without executing secondary HTTP GET downloads from temporary links.

Bringing It Together in Code

Implementing a request utilizing these specific parameters typically follows an OpenAI-compatible client pattern configured for xAI’s base URLs. Below is an example demonstrating how to invoke grok-imagine-image-2.0 with an explicit widescreen aspect ratio and base64-encoded output:

import base64
import os
from openai import OpenAI

# Initialize the client pointing to xAI's API base URL
client = OpenAI(
    api_key=os.environ.get("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A futuristic cyberpunk Tokyo street at midnight, neon reflections on wet pavement, cinematic lighting",
    n=1,
    response_format="b64_json",
    extra_body={
        "aspect_ratio": "16:9",
        "resolution": "2k",
        "quality": "medium",
    },
)

# Extract and decode the base64 payload
image_data_b64 = response.data[0].b64_json
image_bytes = base64.b64decode(image_data_b64)

# Write directly to disk
output_path = "cyberpunk_tokyo.jpg"
with open(output_path, "wb") as f:
    f.write(image_bytes)

print(f"Successfully saved generated asset to {output_path}")

Best Practices for Production Scale

1. Monitor Multi-Reference Constraints: If your workflow shifts from text-to-image generation to image editing (utilizing reference images), ensure your client enforces strict limits (typically capped at 1 to 3 reference images for 2.0 versions to prevent request failure).
2. Select Resolution Intentionally: Use 1k resolutions for rapid batch drafting, user-facing UI previews, or low-latency iterations, reserving 2k and medium quality settings for final-asset pipelines where cropping and deep visual fidelity matter.
3. Secure Your Credentials: Keep your xAI API tokens isolated in server-side environment variables, ensuring that base64 data pipelines and generation keys are never exposed to client-side code bundles.