Grok Image Generation API: Aspect Ratio & Base64 Guide

Mastering Image Generation with xAI’s Grok Imagine API

xAI’s Grok Imagine suite brings powerful visual generation capabilities to developers through an OpenAI-compatible API interface. Powered by models like grok-imagine-image-2.0, the image generation endpoint allows you to transform text descriptions into high-quality digital assets programmatically.

To get the most out of your programmatic image pipelines, understanding key configuration parameters—specifically aspect_ratio and response_format—is essential for matching outputs to your exact design and architecture requirements.

Tailoring Layouts with aspect_ratio

When generating images, the shape of the canvas is just as important as the subject matter. By default, if you omit the aspect_ratio parameter, the model automatically selects the best layout based on your prompt text (auto).

However, when building production workflows, you often need strict layout consistency. The xAI API supports 15 distinct fixed aspect ratios alongside the default choice:

• Square (1:1): Ideal for social media posts, avatars, and thumbnails.
• Landscape (16:9, 4:3, 3:2, 2:1, 21:9, etc.): Perfect for desktop wallpapers, cinematic banners, and photography-style layouts.
• Portrait (9:16, 3:4, 2:3, 1:2, etc.): Tailored for mobile stories, vertical feeds, and portrait photography.
• Modern Mobile Formats (19.5:9, 20:9): Optimized for contemporary smartphone screen dimensions.

Handling Data Efficiently: response_format (url vs. b64_json)

By default, the API returns generated images as temporary hosted URLs (response_format: "url"). While convenient for quick previews, these links are temporary, meaning you must download or process them promptly.

For applications where you want to embed images directly into payloads, avoid managing secondary download fetches, or process bytes inline, you can switch the output type:

{
  "model": "grok-imagine-image-2.0",
  "prompt": "A futuristic cityscape at dusk with neon reflections",
  "aspect_ratio": "16:9",
  "resolution": "2k",
  "response_format": "b64_json"
}

Setting response_format to b64_json populates the response object with a base64-encoded string (b64_json) instead of a URL. This allows your application to immediately stream, save, or render the asset directly from the API response body.

Additional Configuration Parameters

To fine-tune your generation pipeline beyond dimensions and encoding, the API exposes several companion parameters:

• resolution: Choose between 1k for faster iterations and drafts, or 2k for high-detail final production assets.
• quality: Control rendering depth with low, medium, or auto. Pinning medium is particularly useful when intricate text or fine details need to stay sharp.
• n: Generate multiple images in a single batch (ranging from 1 to 10 outputs).

Summary

Whether you are automating social media content creation or embedding custom imagery straight into an application interface via base64 strings, combining grok-imagine-image-2.0 with precise control over aspect_ratio and response_format gives you full architectural flexibility.