> ## 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 2 Image Gen & Editing
> Complete guide to Grok Imagine 2, xAI's latest-generation image model (grok-imagine-image / grok-imagine-image-quality) on APIYI β 5 aspect ratios, 1K/2K tiers, up to 10 images per call, true reference-image editing, flat $0.02 / $0.045 per image.
## Overview
**Grok Imagine 2** is xAI's **latest, second-generation** image model β a full generational step up from the first release in both parameter control and editing: aspect ratio and resolution genuinely take effect, the 2K tier is available, a single call returns up to 10 images, and reference editing truly preserves the source image.
APIYI offers two variants: `grok-imagine-image` (standard) and `grok-imagine-image-quality` (high quality). Both share the same endpoints and parameters β they differ only in output fidelity and price.
**Highlights**: flat per-request pricing (**1K and 2K cost the same**), 5 aspect ratios x 2 resolution tiers that **genuinely take effect**, up to 10 images per call, and high-fidelity reference editing that preserves art style, composition, palette and subject identity. A 1K image takes about 9 seconds.
**The model IDs do not contain a `2`.** The product is named Grok Imagine 2, but the model names you call are **`grok-imagine-image`** and **`grok-imagine-image-quality`** β do not write `grok-imagine-2-image`, which returns 503 because no such model exists.
**π Read this first**: **reference images only work with the editing endpoint `/v1/images/edits` β never with text-to-image.**
Passing `image` / `image_url` / `images` to `/v1/images/generations` returns **200 with a perfectly normal image**, but the reference is **silently discarded** and you are still billed β with no error of any kind. See [Endpoints](#endpoints) below.
All image APIs are **synchronous**: there is no async task ID, so if the client disconnects the result is lost while the request is still billed. Set a generous timeout β see [Image API Best Practices](/en/api-capabilities/image-api-best-practices).
Generate images from a text prompt, with an interactive Playground for live testing.
Upload reference images plus an instruction, with 1-3 image fusion and a Playground.
## Why Grok Imagine 2 on APIYI
Standard `/v1/images/generations` and `/v1/images/edits` endpoints. Request bodies and response fields match the OpenAI Images API, so the official OpenAI SDK works directly β zero migration effort.
No RPM/RPD hard limits. **Measured comfortably at 100 RPM** with ample channel capacity, so batch workloads scale linearly β no quota requests or self-imposed throttling needed.
Fixed price per image, **independent of resolution** β a 2K image costs the same as 1K. Budget to the exact image count, and stack [recharge bonuses](/en/faq/recharge-promotions) to lower it further.
**No overseas server or proxy required.** Mainland data centers, home broadband and overseas nodes all connect directly to `api.apiyi.com`.
Also available: [Nano Banana 2](/en/api-capabilities/nano-banana-2-image/overview), [GPT-Image-2](/en/api-capabilities/gpt-image-2/overview), [Seedream](/en/api-capabilities/seedream-image/overview), [FLUX](/en/api-capabilities/flux/overview), plus the [Grok text models](/en/api-capabilities/grok/overview).
Our team works deeply with image generation workloads and can support enterprise customers from PoC through production rollout.
## Key Features
`1k` at roughly 1 megapixel, `2k` at 4.2-4.5 megapixels (2816x1584 at 16:9) β **same price**
`1:1` / `16:9` / `9:16` / `4:3` / `3:4`, with measured pixel dimensions matching exactly
`n` accepts 1-10, returning multiple images in one request β ideal for batch selection
About 9s at 1K and 15-17s at 2K, with stable latency under load β 100 RPM runs comfortably
Changes only what you ask for β art style, composition, palette and subject identity stay intact
The editing endpoint accepts 1-3 reference images, e.g. placing a subject from image A into image B's scene and style
`url` direct links or `b64_json` raw base64, supported on both endpoints
`client.images.generate()` and `client.images.edit()` work out of the box β no manual HTTP plumbing
## Pricing
| Model | Billing | APIYI price | Notes |
| -------------------------------- | ---------------- | ------------------- | -------------------------------------- |
| **`grok-imagine-image`** | Flat per request | **\$0.02 / image** | Standard tier, the default choice |
| **`grok-imagine-image-quality`** | Flat per request | **\$0.045 / image** | High-quality tier for demanding output |
**Billing notes**
* **Resolution-independent**: `1k` and `2k` cost the same β 2K carries no surcharge.
* **Per image**: `n=4` bills as 4 images, regardless of prompt length.
* **Editing costs the same** as text-to-image β `/v1/images/edits` carries no premium.
* **The `usage` block cannot be used for reconciliation**: `prompt_tokens` is always `1000 x n`, a placeholder. Use the Console billing records instead.
## Group Setup
Grok Imagine 2 runs in the **`Default` Group (1.0x rate)**, matching the pricing table above. **No Group switching is required.**
**Recommended Token billing model**: `Pay-as-you-go Priority`. This family is billed per request, and both Pay-as-you-go Priority and Pay-per-request route correctly β choosing Pay-as-you-go Priority lets a single Token also cover token-billed models elsewhere on the platform.
If your Token already covers other image models, simply keep `Default` as the primary Group. This family needs no dedicated Group or extra configuration.
## Technical Specifications
| Item | Specification |
| -------------------------- | --------------------------------------------------- |
| Model IDs | `grok-imagine-image`, `grok-imagine-image-quality` |
| Aspect ratios | 5: `1:1` / `16:9` / `9:16` / `4:3` / `3:4` |
| Resolution tiers | `1k` (\~0.9-1.05 MP), `2k` (\~4.2-4.5 MP) |
| Output format | **JPEG at 1K (\~220-300 KB), PNG at 2K (\~5-6 MB)** |
| Images per call | `n` 1-10 |
| Reference images | 1-3 on the editing endpoint (repeated `image[]`) |
| Mask inpainting | β Not supported |
| Reproducible `seed` | β Not supported |
| `revised_prompt` echo | β Not returned |
| Latency | \~9s at 1K, \~15-17s at 2K |
| Concurrency / rate | Uncapped; **measured comfortably at 100 RPM** |
| Recommended client timeout | 360 seconds or more |
## Endpoints
| Capability | Method | Path | Content-Type |
| --------------------- | ------ | ------------------------ | ------------------------- |
| Text-to-image | `POST` | `/v1/images/generations` | `application/json` |
| Image editing | `POST` | `/v1/images/edits` | **`multipart/form-data`** |
| Chat-style generation | `POST` | `/v1/chat/completions` | `application/json` |
**β
The editing endpoint requires `multipart/form-data` file upload**
Sending JSON to `/v1/images/edits` **always returns 400**:
```text theme={null}
request Content-Type isn't multipart/form-data
```
**This matters most if you are integrating from the upstream vendor's documentation** β that doc describes a JSON body with a public image URL, which does **not** work through the APIYI gateway. **Follow this page instead**: upload the file with `-F "image=@photo.jpg"`. Full examples in [Image Editing API](/en/api-capabilities/grok-imagine-image/image-edit).
The file field must be named `image` or `image[]`; `images` / `image_file` return 415.
**β οΈ Never send reference images to the text-to-image endpoint**
When `/v1/images/generations` receives `image` / `image_url` / `images`, it does **not** raise an error. It returns 200 and generates a brand-new image from the prompt alone, ignoring your reference entirely β **and bills you as usual**.
Because there is no error signal, this typically surfaces only when someone notices the output has nothing to do with the input. **Any workflow involving a reference image must use `/v1/images/edits`.**
Primary domain `https://api.apiyi.com`, backup `https://vip.apiyi.com`. Chat-style generation (`/v1/chat/completions`) works but is **not the recommended path** β see the FAQ below.
## Migrating from GPT-Image-2
If you already integrate [GPT-Image-2](/en/api-capabilities/gpt-image-2/overview), the **endpoints and calling convention are identical** (`/v1/images/generations` + `/v1/images/edits`, OpenAI SDK compatible) β but the **parameter system is different**, so simply swapping the model name will not work. Here is what must change.
### Parameter mapping
| Aspect | GPT-Image-2 | **Grok Imagine 2** | Migration action |
| ----------------------- | ------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- |
| Output size | `size` (explicit pixels such as `1536x1024`) | `aspect_ratio` + `resolution` | **Must be rewritten**; `size` raises no error |
| Quality tier | `quality` (`low`/`medium`/`high`/`auto`) | No such parameter β **use the model name** | Drop `quality`, switch to the `-quality` variant |
| Output format | `output_format` (png/jpeg/webp) + `output_compression` | No such parameter β **format follows resolution** | Drop both; 1K is always JPEG, 2K always PNG |
| Background | `background` (`opaque`/`auto`) | No such parameter | Drop it |
| Moderation level | `moderation` (`auto`/`low`) | No such parameter | Drop it |
| High fidelity | `input_fidelity` must not be sent | No such parameter | Drop it |
| Images per call | `n` **supports only 1** | `n` **supports 1-10** | β
You can remove the client-side fan-out loop |
| Reference images (edit) | Up to 16 | **Up to 3** | β οΈ Rework flows that send more than 3 |
| Mask inpainting | β
Supported | β **Not supported** | β οΈ Mask-dependent flows cannot migrate |
| Billing | Per token (\~\$0.21/image at high) | **Flat per request**, \$0.02 / \$0.045 | Budget model shifts from usage-based to per-image |
### The three easiest mistakes
**1. The default response format is inverted β the most commonly missed change**
GPT-Image-2 **only returns `b64_json`** (there is no `url`), while Grok Imagine 2 **returns `url` by default**. If your parser reads `resp.data[0].b64_json`, it will get `None` / `undefined` after migrating.
Pick one of two fixes:
* **Keep your existing code** β explicitly pass `"response_format": "b64_json"`
* **Switch to direct links** β read `data[0].url` and download it
Also note that GPT-Image-2's `usage` carries **real token counts**, whereas Grok Imagine 2's `usage` is a **placeholder** (always `1000 x n`). Any cost-reporting script built on `usage` will produce wrong numbers after migrating.
**2. `size` fails silently rather than erroring**
GPT-Image-2 validates strictly and usually returns 400 on bad input. **Grok Imagine 2 is lenient**: OpenAI-style fields such as `size`, `quality` and `style` are **silently ignored**, and invalid `aspect_ratio` / `resolution` values **silently fall back to defaults**.
So if you change only `model` and forget to remove `size: "1536x1024"`, the request **returns 200 with a 1024x1024 square image** β with nothing telling you the parameter was ignored.
After migrating, **verify the output pixel dimensions on the first call** to confirm `aspect_ratio` / `resolution` actually took effect.
**3. Reference images can no longer go to the text-to-image endpoint**
This pitfall is specific to this model: sending a reference image to `/v1/images/generations` returns **200, silently discards the reference, and still bills you**. Every reference-image call must use `/v1/images/edits` with `multipart/form-data` β see [Endpoints](#endpoints) above.
### Before and after
```python theme={null}
# Before: GPT-Image-2
resp = client.images.generate(
model="gpt-image-2",
prompt="Cyberpunk city on a rainy night",
size="1536x1024", # <- remove
quality="high", # <- remove
output_format="jpeg" # <- remove
)
img = base64.b64decode(resp.data[0].b64_json)
# After: Grok Imagine 2
resp = client.images.generate(
model="grok-imagine-image", # use grok-imagine-image-quality for higher fidelity
prompt="Cyberpunk city on a rainy night",
n=1,
extra_body={
"aspect_ratio": "16:9", # <- replaces size
"resolution": "1k", # <- replaces the sizing role of quality
"response_format": "b64_json" # <- set explicitly to keep the parser unchanged
}
)
img = base64.b64decode(resp.data[0].b64_json)
```
**Which should you use?** Stay on [GPT-Image-2](/en/api-capabilities/gpt-image-2/overview) if you need mask inpainting, pixel-exact custom sizes, or fusion across up to 16 references. Choose Grok Imagine 2 for **predictable cost** (flat per image, no 2K surcharge), **multiple images per call** (`n` up to 10), or **high source fidelity when editing**. The two coexist β the same Token calls both.
## Key Parameters
### `aspect_ratio` and `resolution` (output size)
Together these determine the actual output pixels. Measured values match the request exactly:
| `aspect_ratio` | `resolution: 1k` | `resolution: 2k` |
| -------------- | ---------------- | ---------------- |
| `1:1` | 1024x1024 | 2048x2048 |
| `16:9` | 1280x720 | 2816x1584 |
| `9:16` | 720x1280 | 1584x2816 |
| `4:3` | 1152x864 | 2368x1776 |
| `3:4` | 864x1152 | 1776x2368 |
**Both parameters only apply to text-to-image.** On `/v1/images/edits` they are accepted without error but have **no effect** β the edited output always matches **the input reference image's dimensions** (1280x720 in, 1280x720 out). To change the output size, crop or resize the reference image before uploading.
**Validation is lenient β typos do not raise errors.** Values outside the enum for `aspect_ratio` (e.g. `5:7`, `21:9`) or `resolution` (e.g. `1K`, `1024x1024`) **silently fall back to the default** and still return an image. An invalid `response_format` likewise falls back to `url`. So when output does not match expectations, **check your parameter spelling first**.
The one exception is `resolution: "4k"`, which returns `503 model_service_unavailable`. That means **the tier is unsupported**, not that the channel is down β switch back to `1k` / `2k`.
### `n` (images per call)
Accepts **1-10**; the returned `data` array length equals `n`, and each image is billed. `0` is silently treated as `1`; `11` or above returns 400.
## Best Practices
No reference image β `/v1/images/generations`. Any reference image, even for a one-pixel tweak β `/v1/images/edits`. Picking the wrong endpoint produces no error, just an unexpected image.
Image APIs are synchronous. 2K takes 15-17 seconds and can run longer during peaks or cold starts. A 60-second timeout causes spurious failures on requests that are still billed.
The parameter genuinely works, so `aspect_ratio: "16:9"` is far more reliable than asking for a "landscape composition" in the prompt.
2K is lossless PNG at 5-6 MB per image; 1K is JPEG at 220-300 KB β roughly a 20x difference. Prefer 1K for mobile or bulk transfer. Since both tiers cost the same, the choice is purely quality versus bandwidth.
Instructions like "change the scarf to red, keep everything else exactly the same" work very well β the model follows this constraint closely and preserves the rest of the image.
The `image[]` upload order is what "image 1 / image 2 / image 3" means. Writing "put the subject from image 1 into the scene from image 2" is far more reliable than letting the model guess.
This family does not support `seed`; the same prompt yields different results across calls. Persist the images you want to keep rather than expecting to regenerate them.
There are no concurrency limits β **100 RPM runs comfortably** with ample channel capacity. No need to build a serial queue or request extra quota.
## Error Codes and Retries
| HTTP | code | Meaning | Recommended handling |
| ----- | --------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| `400` | `invalid_image_request` | Editing endpoint received JSON instead of multipart | Switch to `multipart/form-data` upload; do not retry |
| `400` | `invalid_request` | Invalid parameters **or** prompt blocked by moderation | Same code for both β check parameters first, then revise the prompt |
| `415` | β | Unsupported file field name on the editing endpoint | Rename the field to `image` or `image[]` |
| `429` | β | Rate limit exceeded or insufficient balance | Exponential backoff, and check the account balance |
| `503` | `model_service_unavailable` | Unsupported parameter tier (e.g. `resolution: 4k`) | **Not an outage** β switch back to `1k` / `2k`, do not retry |
| `503` | β | No available channel in the current Group | Check the Token's Group settings, see Group Setup above |
**Client guidance**: `400` and `415` are deterministic β retrying is pointless, so alert instead. Only `429` and network-layer timeouts are worth retrying, with exponential backoff and at most 3 attempts.
Note that `400 invalid_request` covers both "bad parameter" and "content blocked", and **the response body cannot distinguish them**. A practical heuristic is latency: moderation blocks return in about 5-6 seconds β faster than a successful generation (\~9s) β because the block happens before generation starts.
## FAQ
Because **the APIYI gateway's editing endpoint only accepts `multipart/form-data`**, while the upstream vendor documentation describes a JSON body with a public image URL. The two differ β follow this site's documentation.
The correct form is a file upload:
```bash theme={null}
curl -X POST "https://api.apiyi.com/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=grok-imagine-image" \
-F "prompt=Change the scarf to red, keep everything else the same" \
-F "image=@photo.jpg"
```
The upside is that you **do not need image hosting** β upload the local file directly, which is simpler than preparing a public URL. Full examples in [Image Editing API](/en/api-capabilities/grok-imagine-image/image-edit).
That is expected behaviour, and the **most common pitfall** with this model: `/v1/images/generations` **silently ignores** `image` / `image_url` / `images`, generates purely from the prompt, and **bills you as usual**.
With no error signal it is easy to conclude that "editing is broken". **Any workflow with a reference image must use `/v1/images/edits`.**
Edited output dimensions **follow the input reference image**: 1280x720 in gives 1280x720 out, 1024x1024 in gives 1024x1024 out. Passing `resolution` or `aspect_ratio` here raises no error but does nothing.
To change the output size, crop or resize the reference image before uploading.
This family does **not** return `revised_prompt`, nor fields like `respect_moderation` or `model`. Each `data[]` entry contains **either** `url` **or** `b64_json` depending on `response_format` β never both.
Do not assume these fields exist when parsing responses.
**No.** `usage.prompt_tokens` is always `1000 x n` regardless of actual prompt length β it is a placeholder.
This family is billed **per request** at a flat rate per image. Use the APIYI Console billing records for actual charges.
That is upstream behaviour: `resolution: 1k` returns JPEG (\~220-300 KB) and `resolution: 2k` returns lossless PNG (\~5-6 MB), roughly a 20x difference.
The URL extension, the HTTP `Content-Type` and the actual bytes are consistent with each other, so you can branch safely on `Content-Type`.
For bandwidth-sensitive scenarios (mobile, bulk transfer) prefer `1k` β both tiers cost the same, so the decision is purely about quality.
**No.** `4k` is not a supported tier for this family, and the gateway returns `503 model_service_unavailable`. The code looks like an outage but is really a parameter problem, so **retrying will not help** β switch back to `1k` or `2k`.
Only `1k` and `2k` are supported.
Validation on this family is lenient: invalid `aspect_ratio` (e.g. `5:7`), `resolution` (e.g. `1K`, `1024x1024`) and `response_format` (e.g. `base64`) all **silently fall back to defaults** and still return an image rather than a 400.
So when the output does not match expectations, **check the parameter spelling first** β in particular, `resolution` values are lowercase `1k` / `2k`.
`n` accepts **1-10**, and the returned `data` array length equals `n`. Each image **is billed**.
`0` is silently treated as `1`; `11` or above returns `400 invalid_request`.
**No.** Passing `seed` raises no error but has no effect β the same prompt with the same `seed` returns different images across calls.
Persist any image you need to reuse rather than trying to regenerate it.
Yes. Both endpoints are OpenAI Images API compatible β just point `base_url` at `https://api.apiyi.com/v1`:
```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",
prompt="a red wooden boat on an alpine lake at dawn",
extra_body={"aspect_ratio": "16:9", "resolution": "1k"}
)
```
Note that `aspect_ratio` and `resolution` are not standard OpenAI SDK fields, so pass them via `extra_body`.
**No concurrency limits.** **Measured comfortably at 100 RPM** with no 429s and no queue rejections, backed by ample channel capacity. Call concurrently without building a serial queue or requesting extra quota.
What actually matters is **`timeout`**: image APIs are synchronous, so set the client timeout to **360 seconds** to avoid cutting off requests that are still processing normally β and still being billed.
This family applies content moderation. Blocked requests return `400 invalid_request` using **exactly the same error code and message as a parameter error**, so the response body cannot distinguish them.
A practical heuristic is **latency**: moderation blocks return in about 5-6 seconds (the block precedes generation), while a successful image takes about 9 seconds. Moderation outcomes also carry some randomness, so borderline content may not behave identically across retries β **do not draw conclusions from a single attempt**.
If parameters are verified correct and 400s persist, the prompt most likely triggered moderation; revise the wording.
Yes, but it is **not the recommended path**. The endpoint returns a standard chat structure whose `content` is a markdown image link:
```text theme={null}
```
That suits conversational clients such as Chatbox or LobeChat. For programmatic integration, **use the Images API** (`/v1/images/generations` and `/v1/images/edits`) β richer parameters, a more stable response shape, and consistent with this documentation.
## Related Documentation
* [Grok Imagine 2 Text-to-Image API](/en/api-capabilities/grok-imagine-image/text-to-image) - endpoint reference with Playground
* [Grok Imagine 2 Image Editing API](/en/api-capabilities/grok-imagine-image/image-edit) - reference editing and multi-image fusion
* [Grok Model Guide](/en/api-capabilities/grok/overview) - xAI text models
* [Image API Best Practices](/en/api-capabilities/image-api-best-practices) - timeouts, disconnects, compression
* [API Manual](/en/api-manual)
* [Recharge Promotions](/en/faq/recharge-promotions)