xAI Grok Image Generation: aspect_ratio & b64_json

Mastering the xAI Imagine API: A Developer’s Guide to Aspect Ratios, Base64 Encoding, and Grok Image Generation

If you are looking to integrate cutting-edge visual generation into your applications, xAI’s Grok Imagine API offers some of the fastest and most flexible text-to-image and image-editing pipelines on the market.

When diving into the documentation (docs.x.ai), developers frequently home in on specific configuration parameters to control layout, output quality, and payload formats. Among the most critical parameters for production environments are aspect_ratio and response_format (specifically b64_json).

Core Parameters for Grok Image Generation

When making a request to models like grok-imagine-image-2.0, you can precisely fine-tune how your images are structured and returned.

1. Controlling Layout with aspect_ratio

Instead of guessing pixel dimensions or relying on generic size fields, the Grok Imagine API uses flexible, predefined aspect ratio strings. If omitted, the model will choose a default layout, but specifying a ratio ensures your UI components or downstream pipelines receive predictable compositions.

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

Pro-tip: Selecting an aspect ratio like 3:2 combined with a 2k resolution will automatically scale output dimensions to optimal sizes (such as 1248×832) while preserving fine visual details.

2. Managing Payload Data: url vs. b64_json

By default, image generation endpoints return a temporary public URL pointing to the asset. However, handling temporary links introduces expiration risks if you plan on archiving or processing the file later.

• url (Default): Returns a temporary hosted link (data[].url). Best for quick frontend testing or instant rendering where your client handles immediate caching.
• b64_json: Instructs the API to return the raw image encoded as a Base64 string (data[].b64_json) directly inside the JSON response payload. This is ideal when you need to stream bytes straight into local storage, databases, or microservices without making a secondary network request to download a temporary file.

Sample Request Structure

Here is how you can pull these parameters together in a standard JSON payload configuration targeting the Grok Imagine endpoint:

{
  "model": "grok-imagine-image-2.0",
  "prompt": "A futuristic cyberpunk city skyline at twilight with neon lights reflecting on wet streets",
  "aspect_ratio": "16:9",
  "resolution": "2k",
  "quality": "medium",
  "response_format": "b64_json"
}

Best Practices for Production

• Watch Your Resolutions: Stick to 1k for rapid prototyping, batch candidate generation, or speed-critical drafts. Upgrade to 2k when fine details, text legibility, or clean cropping are necessary for final assets.
• Quality Settings: Explicitly pass quality="low" or quality="medium" depending on your performance budget. Avoid unsupported arguments to prevent silent fallbacks or unnecessary errors.
• Handle Storage Proactively: If you opt for standard URL generation, make sure your worker scripts download and persist the assets immediately before expiration. Alternatively, use b64_json to manage the byte streams natively in your application workflow.

By leveraging exact aspect ratios and choosing the right response formatting, you can seamlessly blend Grok’s powerful visual generation capabilities into any modern web or mobile backend architecture.