Grok Imagine Official Image Generation

Overview

Grok Imagine Official is the official channel for xAI’s image models: requests are relayed by APIYI to the official xAI API, pricing matches xAI’s list price, billing follows resolution and quality tier, and parameter validation is the same as upstream. Three models are available: the standard grok-imagine-image, the high-quality grok-imagine-image-quality, and the newer grok-imagine-image-2.0 (with low / medium quality tiers).

🔒 This channel requires the GrokOfficial group, granted on applicationGrok Imagine Official is not in the Default group. This family’s content-safety policy differs substantially from the other models on the platform, so to limit compliance risk we grant access selectively:

Existing customers with $1,000+ in cumulative spend: contact support, describe your use case, and we enable it after verification
Everyone else: apply through WeCom support, describing your use case and your content-moderation controls; we enable it once approved

A Token without the GrokOfficial group returns 503 — a permissions problem, not an outage. See Group Setup below.

Official or reverse? This page is the official channel: same price as xAI, billed by tier, includes grok-imagine-image-2.0, and currently offers text-to-image only, one image per call. If you need image editing or multiple images per call, or a lower flat price ($0.02 / $0.045 per image regardless of resolution), use Grok Imagine Reverse. See Official vs reverse for a side-by-side comparison.

All image APIs are synchronous: there is no async task ID, so if the client disconnects the result is lost but the request is still billed. grok-imagine-image-2.0 at medium quality and 2K takes about 60–80 seconds in our tests, so give this model a generous timeout. See Image API Notes & Best Practices.

Text-to-Image API

Generate images from a text prompt, with an interactive Playground.

Grok Imagine Video

Same GrokOfficial group — text-to-video and image-to-video, billed per second.

Let an AI Agent Integrate It

Copy this prompt and paste it into Codex / Claude Code / Cursor

It fetches the plain-text version of this page first (append .md to any docs URL), then writes code for your stack — timeouts, saving URL results right away, using resolution instead of size, and one image per call are already baked into the requirements.

Integrate / troubleshoot Grok Imagine Official text-to-image in this project.

Read the docs before writing code: fetch https://docs.apiyi.com/en/api-capabilities/grok-imagine-image-official/overview.md for the plain-text version of this page; …

Pick one model: grok-imagine-image, grok-imagine-image-quality, or grok-imagine-image-2.0 …

8 requirements in total — use the button below to copy the full version

Models & Pricing

Pricing matches xAI’s list price and is charged per image; the tier is set by resolution (plus quality for 2.0):

Model	Quality tier	`1k`	`1.5k`	`2k`
`grok-imagine-image`	—	$0.02	$0.02	$0.02
`grok-imagine-image-quality`	—	$0.05	$0.06	$0.07
`grok-imagine-image-2.0`	`low` (default)	$0.04	$0.05	$0.06
`grok-imagine-image-2.0`	`medium`	$0.06	$0.07	$0.08

Model pricing is aligned with the official sites and may change when they do; the table above is for reference only, and the Model Pricing tab in the top navigation is authoritative: Model Pricing.

Billing notes

Defaults: resolution defaults to 1k; grok-imagine-image-2.0 defaults to quality: low, i.e. $0.04 per image.
Per image, one per call: keep n=1 on this channel and call concurrently when you need more images.
Failed requests are not billed: parameter errors (422 / 400), missing group access (503), and other error responses are free.
Do not reconcile with usage: prompt_tokens is always 1000 × image count, a placeholder; the console billing records are authoritative.
Tiered top-up bonuses apply on top; high-volume business customers can contact sales about dedicated pricing.

Official vs reverse

APIYI offers both an official and a reverse channel for Grok Imagine. They differ in group, billing, and capabilities:

Aspect	Official (this page)	Reverse
Group	`GrokOfficial` (by application)	`Grok_imagine_Reverse` (by application)
Billing	Same as xAI list price, metered by resolution × quality tier	Flat per image, regardless of resolution
Models	`grok-imagine-image` / `-quality` / `-2.0`	`grok-imagine-image` / `-quality`
Resolution tiers	`1k` / `1.5k` / `2k`	`1k` / `2k`
Text-to-image	✅	✅
Image editing / multi-image fusion	Not offered yet	✅ 1–4 reference images
Multiple images per call	Not offered yet (`n=1`)	✅ `n` up to 10
Parameter validation	Strict: out-of-range values return 422	Lenient: invalid values silently fall back to defaults

How to choose: if you need grok-imagine-image-2.0, want billing on xAI’s own terms, or want typos to fail loudly → official. If you need editing, several images per call, or the lowest price for 2K output → reverse. You can have both groups and call each with its own Token.

Group Setup

Grok Imagine Official is not in the Default group. It lives in the GrokOfficial group (same price as xAI, i.e. the table above), and access must be requested.

Who can get access

Customer type	How to get access
Existing customers with $1,000+ cumulative spend	Contact support with your use case; enabled after verification
Everyone else	Apply with your use case and content-moderation controls; enabled once approved

How to apply

Contact WeCom support

Apply through WeCom support, or email [email protected]. Say you are applying for GrokOfficial (Grok Imagine Official).

Describe your use case and moderation controls

Cover three things: what the images are for, who the end users are, and what content review and human checks you run on your side. The more specific, the faster the review.

Switch your Token group once approved

Once approved, we enable GrokOfficial on your account. Go to the Token page in the console, switch the Token you use for this channel to GrokOfficial, and set the billing mode to Pay-as-you-go Priority or Pay-as-you-go.

What it looks like before access is granted: a Token without the GrokOfficial group returns 503 (no available channel in the current group). Retrying will not help — the group has to be enabled first.Do not use the Pay-per-request billing mode: this channel is metered, so a pay-per-request Token cannot be routed and also returns 503.

Compliance reminder: once access is granted, responsibility for generated content lies with the caller. Follow local laws and regulations; do not generate illegal content, content that infringes others’ likeness or intellectual property, or content inappropriate for minors. For consumer-facing distribution, add your own moderation layer. Background: Compliance notes for calling overseas models. We revoke group access when abuse is found.

Technical Specs

Item	Spec
Model IDs	`grok-imagine-image`, `grok-imagine-image-quality`, `grok-imagine-image-2.0`
Endpoint	`POST /v1/images/generations` (`application/json`)
Resolution tiers	`1k` (default) / `1.5k` / `2k`
Aspect ratios	Common: `1:1` (default) / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`
Quality tiers	`grok-imagine-image-2.0` only: `low` (default) / `medium`
Images per call	`n=1`
Response format	`url` (default) or `b64_json`
Parameter validation	Strict — out-of-range `resolution` / `aspect_ratio` returns 422
Latency	`grok-imagine-image` about 8 s; `-quality` about 7 s at 1k and 12 s at 2k; `-2.0` `low` about 15–17 s, `medium` 2K about 60–80 s
Recommended client timeout	≥ 360 seconds

Key Parameters

`resolution` and `aspect_ratio` (output size)

Together they determine the output pixels. Some measured results:

Model	Request	Actual output
`grok-imagine-image`	`1k` + `3:2`	1248×832 (JPEG)
`grok-imagine-image-quality`	`2k` + `9:16`	1584×2816 (PNG, about 6.7 MB)
`grok-imagine-image-2.0`	`1.5k` + `16:9` + `medium`	1792×1008

Use resolution, not sizeThis channel does not map an OpenAI-style size (such as "2048x2048") to a resolution tier: passing size raises no error, but the image is generated and billed at the default 1k. For 2K, pass resolution: "2k" explicitly.

Mistakes fail loudly: unlike the reverse channel, parameter validation here matches xAI. Out-of-range values such as resolution: "4k" or aspect_ratio: "5:7" return 422 and are not billed. When you see a 422, check the spelling of these two parameters first (all lowercase: 1k / 1.5k / 2k).

`quality` (`grok-imagine-image-2.0` only)

Value	Notes
`low`	Default, faster
`medium`	Higher fidelity, $0.02 more per image, about 60–80 s at 2K

Passing high returns 400 (This model only supports the following quality value(s): low, medium, auto). Send only low or medium — do not send auto. grok-imagine-image and grok-imagine-image-quality take no quality; the model itself sets the fidelity.

`n` (image count)

Always send n=1 on this channel. For several images at once, send several requests concurrently — latency is steady, so concurrency scales linearly.

Best Practices

Explore at 1k, finish at 2k

Run a prompt a few times at 1k to pick a direction, then render the final at 2k. grok-imagine-image-2.0 at medium and 2K takes over a minute, which makes it a poor fit for trial and error.

Set the client timeout to 360 seconds

The image API is synchronous. A 60-second timeout will cause many false timeouts on 2.0 medium, and requests cut off by the client are still billed.

Use aspect_ratio for framing, not the prompt

The parameter genuinely takes effect; aspect_ratio: "16:9" is far more reliable than writing “landscape composition” in the prompt.

Save URL results right away

Download returned image links to your own storage on the server immediately; do not keep referencing them or hand them to end users.

Switch to the reverse channel for editing

This channel does not offer image editing yet. For reference-based edits and multi-image fusion, use /v1/images/edits on Grok Imagine Reverse.

Error Codes & Retries

HTTP	Meaning	What to do
`400`	Invalid `quality` (such as `high`); the message lists the allowed values	Change to `low` / `medium`; do not retry
`422`	`resolution` / `aspect_ratio` outside the allowed set	Check spelling and case; do not retry
`429`	Rate limit hit or insufficient balance	Retry with exponential backoff and check your balance
`503`	Token lacks the `GrokOfficial` group, or the Token uses pay-per-request billing	Permissions, not an outage — retrying will not help; see Group Setup

Client advice: 400 / 422 are deterministic errors — retrying is pointless, alert on them instead. Only 429 and network-level timeouts are worth retrying, with exponential backoff and at most 3 attempts. Error responses are not billed.

FAQ

Every call returns 503 — is the channel down?

Almost certainly permissions. There are two possibilities:

The Token group lacks GrokOfficial: this channel is granted on application; see Group Setup.
The Token’s billing mode is pay-per-request: this channel is metered and cannot be routed from a pay-per-request Token. Switch the billing mode to Pay-as-you-go Priority or Pay-as-you-go.

I passed size: 2048x2048 — why is the output still 1K?

This channel does not map size to a resolution tier, so the image is generated and billed at the default 1k. Use resolution: "2k" instead and control framing with aspect_ratio.

Can I edit images or pass a reference image?

This channel does not offer image editing yet. Sending a reference image to /v1/images/generations raises no error, but the reference is ignored and a new image is generated from the prompt alone.For editing or multi-image fusion, get access to Grok Imagine Reverse, whose /v1/images/edits accepts 1–4 reference images.

Why n=1? How do I get several images at once?

This channel currently offers single-image output only. For more images, send several requests concurrently with n=1 each. If your workflow genuinely depends on several images per call, use Grok Imagine Reverse (n up to 10).

How does grok-imagine-image-2.0 differ from the other two?

grok-imagine-image-2.0 is xAI’s newer image model and adds a quality tier (low / medium); medium has finer detail but is slower (about 60–80 seconds at 2K). grok-imagine-image is the cheapest and costs the same at every resolution; grok-imagine-image-quality has higher fidelity with tiered pricing by resolution.Get your pipeline working on grok-imagine-image or 2.0 low first, then move up a tier as quality needs dictate.

Can I reconcile my bill with the token counts in usage?

No. usage.prompt_tokens is always 1000 × image count, a placeholder unrelated to actual charges. This channel bills per image by resolution and quality tier; the console billing records are authoritative.

Can I use the official OpenAI SDK?

Yes. The endpoint is compatible with the OpenAI Images API; point base_url at https://api.apiyi.com/v1 and put non-standard fields in extra_body:

from openai import OpenAI
client = OpenAI(api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")

resp = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="a red wooden boat on an alpine lake at dawn",
    n=1,
    extra_body={"resolution": "2k", "aspect_ratio": "16:9", "quality": "medium"},
    timeout=360,
)
print(resp.data[0].url)

Grok Imagine Official Text-to-Image API - API reference with Playground
Grok Imagine Video - same group, text-to-video and image-to-video
Grok Imagine Reverse - flat per-image pricing, with editing and multiple images per call
Image API Notes & Best Practices - general advice on timeouts, disconnects, and compression
Top-up Bonuses

Basics

Basic API

Image API (Official)

Video API (Official)

Multimodal Understanding API

Text Generation

Audio API (Official)

Retrieval & Safety

Grok Imagine Official Image Generation

Overview

Text-to-Image API

Grok Imagine Video

Let an AI Agent Integrate It

Models & Pricing

Official vs reverse

Group Setup

Who can get access

How to apply

Technical Specs

Key Parameters

`resolution` and `aspect_ratio` (output size)

`quality` (`grok-imagine-image-2.0` only)

`n` (image count)

Best Practices

Error Codes & Retries

FAQ

​Overview

Text-to-Image API

Grok Imagine Video

​Let an AI Agent Integrate It

​Models & Pricing

​Official vs reverse

​Group Setup

​Who can get access

​How to apply

​Technical Specs

​Key Parameters

​resolution and aspect_ratio (output size)

​quality (grok-imagine-image-2.0 only)

​n (image count)

​Best Practices

​Error Codes & Retries

​FAQ

​Related Docs

Overview

Let an AI Agent Integrate It

Models & Pricing

Official vs reverse

Group Setup

Who can get access

How to apply

Technical Specs

Key Parameters

`resolution` and `aspect_ratio` (output size)

`quality` (`grok-imagine-image-2.0` only)

`n` (image count)

Best Practices

Error Codes & Retries

FAQ

Related Docs