> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Imagine Official Image Generation

> Complete guide to the Grok Imagine official channel on APIYI: grok-imagine-image / grok-imagine-image-quality / grok-imagine-image-2.0, priced the same as xAI and billed by resolution (1k / 1.5k / 2k) and quality tier (low / medium), $0.02–0.08 per image. Requires the GrokOfficial group by application.

## 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).

> [!WARNING]
>
> **🔒 This channel requires the `GrokOfficial` group, granted on application**
>
> Grok 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](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec), 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](#group-setup) below.

> [!TIP]
>
> **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](/en/api-capabilities/grok-imagine-image/overview). See [Official vs reverse](#official-vs-reverse) for a side-by-side comparison.

> [!NOTE]
>
> 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](/en/api-capabilities/image-api-best-practices).

> **[Text-to-Image API](/en/api-capabilities/grok-imagine-image-official/text-to-image)**
>
> Generate images from a text prompt, with an interactive Playground.

> **[Grok Imagine Video](/en/api-capabilities/grok-imagine-video/overview)**
>
> Same `GrokOfficial` group — text-to-video and image-to-video, billed per second.

## Let an AI Agent Integrate It

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](https://docs.apiyi.com/en/api-capabilities/grok-imagine-image-official/overview.md) for the plain-text version of this page; for more parameter detail, append `.md` to the text-to-image page URL the same way.

Requirements:

1. Pick one model: `grok-imagine-image` (standard), `grok-imagine-image-quality` (high quality), or `grok-imagine-image-2.0` (newer, with two `quality` tiers). The Token group must include `GrokOfficial`, otherwise every call returns 503.

2. Timeout: set the client timeout to 360 seconds as a safety margin. `grok-imagine-image` takes about 8 seconds and `-quality` about 7–12 seconds, but `grok-imagine-image-2.0` at `medium` and 2K takes 60–80 seconds. The image API is synchronous: if the client disconnects, the result is lost and the request is still billed. Raise the limits on reverse proxies, gateways, and serverless runtimes too.

3. Endpoint: use only `/v1/images/generations` (JSON) for text-to-image. **Do not send reference images to this endpoint** (`image` / `image_url` and so on) — they are silently dropped. This channel does not offer image editing yet; for editing use the reverse channel at `/en/api-capabilities/grok-imagine-image/overview`.

4. Size: control the output with `resolution` (`1k` / `1.5k` / `2k`, lowercase) plus `aspect_ratio` (for example `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`). **Do not send `size`** — it is not mapped to a resolution tier, so the image comes out at the default 1k. Values outside the allowed set return 422 instead of falling back silently.

5. Quality: only `grok-imagine-image-2.0` has `quality`; send only `low` (default) or `medium`, never `auto` or `high` (`high` returns 400). The other two models need no `quality` — pick the model to choose fidelity.

6. Count: always send `n` = 1. For several images, send several requests concurrently instead of using `n`.

7. Response handling: the default is `url`; you can also send `response_format: "b64_json"`. If you use URLs, download and store the image on your server right away instead of keeping the link. The `usage` field is a placeholder (`prompt_tokens` is always 1000 times the image count) and **cannot be used for reconciliation** — check the console billing records.

8. Read the key from the `APIYI_API_KEY` environment variable and use [https://api.apiyi.com/v1](https://api.apiyi.com/v1) as base\_url; never hard-code it or commit it to git. When done, actually run one text-to-image call and show me the output and what that call cost.

## 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 |

> [!NOTE]
>
> 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](/en/models/index).

> [!NOTE]
>
> **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](/en/faq/recharge-promotions) 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**](/en/api-capabilities/grok-imagine-image/overview) |
| - | - | - |
| 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 |

> [!TIP]
>
> **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

> [!WARNING]
>
> **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

**1. Contact WeCom support**

Apply through [WeCom support](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec), or email [hi@apiyi.com](mailto:hi@apiyi.com). Say you are applying for **`GrokOfficial` (Grok Imagine Official)**.

**2. 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.

**3. Switch your Token group once approved**

Once approved, we enable `GrokOfficial` on your account. Go to the [Token page in the console](https://api.apiyi.com/token), 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`.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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](/en/faq/overseas-model-compliance). 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 |

> [!WARNING]
>
> **Use `resolution`, not `size`**
>
> This 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.

> [!NOTE]
>
> **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

**1. 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.

**2. 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.

**3. 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.

**4. 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.

**5. 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](/en/api-capabilities/grok-imagine-image/overview).

## 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](#group-setup) |

> [!NOTE]
>
> **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:
>
> 1. **The Token group lacks `GrokOfficial`**: this channel is granted on application; see [Group Setup](#group-setup).
> 2. **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](/en/api-capabilities/grok-imagine-image/overview), 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](/en/api-capabilities/grok-imagine-image/overview) (`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`:
>
> ```python theme={null}
> 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)
> ```

## Related Docs

* [Grok Imagine Official Text-to-Image API](/en/api-capabilities/grok-imagine-image-official/text-to-image) - API reference with Playground
* [Grok Imagine Video](/en/api-capabilities/grok-imagine-video/overview) - same group, text-to-video and image-to-video
* [Grok Imagine Reverse](/en/api-capabilities/grok-imagine-image/overview) - flat per-image pricing, with editing and multiple images per call
* [Image API Notes & Best Practices](/en/api-capabilities/image-api-best-practices) - general advice on timeouts, disconnects, and compression
* [Top-up Bonuses](/en/faq/recharge-promotions)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.