> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Grok Imagine 2 API Image Generation and Editing
> LaoZhang API guide to Grok Imagine pricing, five aspect ratios, 1K/2K generation, batching, and model-specific single- and multi-reference editing limits.
LaoZhang API now provides `grok-imagine-image` and `grok-imagine-image-quality` for text-to-image generation, 1K/2K output, batches of up to 10 images, and natural-language editing with reference images. Current LaoZhang API per-image pricing is **\$0.02** for the standard model and **\$0.045** for the quality model. Confirm the available token group, current price, and recorded charge in the [console](https://api2.laozhang.ai/account/pricing).
This guide uses “Grok Imagine 2” as the product label for the current Grok Imagine image generation. The request model IDs do **not** contain `2`: use `grok-imagine-image` or `grok-imagine-image-quality`.
Create a token and confirm its model group, balance, and billing mode
Check the publication date, scope, pricing, and current status
## Choose a model
| Model ID | Current LaoZhang price | Resolution | Reference-image boundary | Best for |
| ---------------------------- | ---------------------: | ---------- | ----------------------------------- | -------------------------------------------------------------------- |
| `grok-imagine-image` | **\$0.02/image** | 1K / 2K | 1–4 references verified on LaoZhang | Everyday assets, drafts, fast iteration, and multi-image composition |
| `grok-imagine-image-quality` | **\$0.045/image** | 1K / 2K | LaoZhang supports 1–2 references | Final assets, marketing work, detail, and reference editing |
LaoZhang API currently bills by the number of generated images, so `n=4` is four image charges. 1K and 2K currently have the same LaoZhang price. xAI list pricing and LaoZhang API pricing are separate billing contracts; use the console and latest announcement for current LaoZhang rates.
## Current integration scope
| Item | Current LaoZhang documented scope |
| ------------------------------ | --------------------------------------------------------------- |
| Text-to-image endpoint | `POST /v1/images/generations` |
| Reference-image editing | `POST /v1/images/edits` |
| Aspect ratios | `1:1`, `16:9`, `9:16`, `4:3`, `3:4` |
| Resolution | `1k`, `2k` |
| Images per request | `n` from 1 through 10 |
| Standard-model references | `grok-imagine-image` supports 1–4 files |
| Quality-model references | `grok-imagine-image-quality` supports 1–2 files |
| Response format | `url` or `b64_json` |
| Outside the current commitment | 4K, mask inpainting, reproducible `seed`, arbitrary pixel sizes |
xAI documents additional aspect ratios upstream. This LaoZhang page commits only to the five values above. Treat any other ratio as unverified on the current gateway until a later documentation or console update expands the scope.
`n=10` means up to ten generated **output images** in one request. It is not a ten-reference input limit; reference counts are model- and route-specific.
## Prerequisites
Create a key in [Token Management](https://api2.laozhang.ai/token). Never expose it in browser code, a public repository, or logs.
Check the [model pricing page](https://api2.laozhang.ai/account/pricing) for the target token group and current rate. A new announcement does not retroactively change earlier charges.
Use the production token, prompt, and parameters to generate one image. Check the HTTP status, `data` array, actual dimensions, downloaded file, and call log before increasing `n` or concurrency.
## Text-to-image quick start
Use the OpenAI-compatible Images endpoint:
```bash theme={null}
curl https://api2.laozhang.ai/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image",
"prompt": "A minimalist technology product poster, deep blue background, crisp typography, studio lighting",
"n": 1,
"aspect_ratio": "16:9",
"resolution": "2k",
"response_format": "url"
}'
```
A successful response is HTTP 200 with one readable image item in `data`. When requesting `url`, download the file promptly instead of treating a temporary URL as permanent storage.
### Python SDK
```python theme={null}
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["LAOZHANG_API_KEY"],
base_url="https://api2.laozhang.ai/v1",
)
response = client.images.generate(
model="grok-imagine-image-quality",
prompt="A premium skincare product on travertine, soft morning light",
n=2,
extra_body={
"aspect_ratio": "4:3",
"resolution": "2k",
"response_format": "url",
},
)
for index, image in enumerate(response.data, start=1):
print(index, image.url)
```
The Python OpenAI SDK does not expose every xAI extension as a first-class parameter. Passing `aspect_ratio`, `resolution`, and `response_format` through `extra_body` is the safest portable form.
## Reference-image editing
Use `/v1/images/edits` whenever the task depends on an existing subject, composition, palette, or style. The current LaoZhang compatibility route accepts `multipart/form-data` file uploads. Do not place a reference-image field in `/v1/images/generations` and treat HTTP 200 alone as proof that editing occurred.
```bash theme={null}
curl https://api2.laozhang.ai/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-imagine-image-quality" \
-F "prompt=Change the mug to matte black. Preserve the subject, composition, lighting, and background." \
-F "image=@product-photo.png" \
-F "response_format=url"
```
For multi-image composition, submit `image[]` repeatedly. Upload order maps to “image 1 / image 2 / image 3 / image 4” in the prompt. LaoZhang currently provides these model-specific ranges:
| Model | References supported by LaoZhang | Recommended use |
| ---------------------------- | -------------------------------- | ----------------------------------------------------------------- |
| `grok-imagine-image` | 1–4 | Three- or four-reference composition and routine multi-image work |
| `grok-imagine-image-quality` | 1–2 | Detailed single-image edits and two-image fusion |
This is the currently runnable four-reference form for the standard model:
```bash theme={null}
curl https://api2.laozhang.ai/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-imagine-image" \
-F "prompt=Place the product from image 1 in the scene from image 2, use the warm film style from image 3, and preserve the brand colors from image 4." \
-F "image[]=@product.png" \
-F "image[]=@scene.jpg" \
-F "image[]=@style.jpg" \
-F "image[]=@brand-reference.png"
```
Requests above the current reference limit return HTTP 400. Limit Quality to two references. For three- or four-reference composition, use `grok-imagine-image` instead of retrying the same over-limit request.
The first reference affects the edit output's aspect ratio. A 1280×720 first image produced 1280×720, while moving a 1200×1200 source to the first position produced 1024×1024. Depend on the first image's orientation, not on exact pixel equality.
Reference editing is not mask-based inpainting. The model reconstructs an output from natural-language instructions. Manually verify identity, logos, text, and exact geometry; one successful sample is not a pixel-perfect fidelity guarantee.
## Parameters
| Parameter | Type | Required | Current values and behavior |
| ------------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `model` | string | Yes | `grok-imagine-image` or `grok-imagine-image-quality` |
| `prompt` | string | Yes | Describe content, composition, style, and what must remain unchanged |
| `n` | integer | No | 1–10 output images; billed by generated output count, not the number of references |
| `aspect_ratio` | string | No | Five documented text-to-image values: `1:1`, `16:9`, `9:16`, `4:3`, `3:4` |
| `resolution` | string | No | Lowercase `1k` or `2k` for text-to-image; `4k` is not currently supported |
| `response_format` | string | No | `url` or `b64_json` |
| `image` / `image[]` | file | For editing | Use `image` for one file and repeat `image[]` for multi-image edits. Standard supports 1–4; Quality supports 1–2 |
Use the following table to validate orientation and resolution class. Read the actual output dimensions in production rather than hard-coding inferred pixel sizes:
| Ratio | 1K orientation | 2K orientation | Common uses |
| ------ | -------------- | -------------- | ------------------------------------- |
| `1:1` | Square | Square | Avatars, product images, social cards |
| `16:9` | Landscape | Landscape | Covers, presentations, thumbnails |
| `9:16` | Portrait | Portrait | Shorts covers and mobile stories |
| `4:3` | Landscape | Landscape | Product imagery and presentations |
| `3:4` | Portrait | Portrait | Portraits and posters |
## Migrating from another Images API
Do not replace only the model name if the existing code uses `size: "1536x1024"` or `quality: "high"`. The current Grok Imagine route uses `aspect_ratio` plus `resolution` for the canvas and separate model IDs for standard and quality output.
| Existing behavior | Grok Imagine 2 migration action |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size: "1536x1024"` | Map to a documented aspect ratio. Note that `3:2` is not among LaoZhang's current five committed values, so choose a documented ratio or test first |
| `quality: "high"` | Select `grok-imagine-image-quality` |
| Parser expects `b64_json` | Set `response_format: "b64_json"`, or read `data[].url` |
| Reference image sent to generations | Move it to `/v1/images/edits` as a file upload |
| Workflow depends on mask or `seed` | Keep the original model or redesign the workflow; these are not currently committed features |
## Production acceptance and errors
1. Generate one 1K `1:1` image with each model to verify token group, price, and response parsing.
2. Test the target ratio and 2K next; read actual dimensions and retain the original response.
3. Use distinct, non-sensitive references and confirm that every subject and identifying feature appears in the entity. HTTP 200 alone does not prove multi-image use.
4. Do not retry an over-limit reference request: reduce Quality to two references or Standard to four.
5. `resolution=4k` can currently return HTTP 503, but this is an unsupported parameter rather than a transient outage; use `1k` or `2k`.
6. Apply jittered exponential backoff to `429` and network errors. Correct other `400`, `401`, or `403` request/account problems before retrying.
7. After a client timeout, check the call log before resubmitting to avoid duplicate charges.
HTTP 200 proves only that the request was processed. It does not prove that the requested ratio, reference, or business constraint was satisfied. Acceptance must inspect dimensions, content, returned item count, and the console charge.
## Frequently asked questions
### What are the Grok Imagine 2 model IDs?
Use `grok-imagine-image` or `grok-imagine-image-quality`. Do not add `2`; `grok-imagine-2-image` is not a model ID documented on this page.
### Which model should I choose?
Start with `grok-imagine-image` at \$0.02/image for routine assets and batch drafts. Compare the same prompt, ratio, and resolution on `grok-imagine-image-quality` at \$0.045/image when final detail or reference editing matters.
### Do 1K and 2K cost the same?
Yes under the current LaoZhang launch pricing. Both resolution classes use the same per-image rate for the selected model. Recheck the console before a large batch because pricing can change.
### Why does this page list only five aspect ratios?
They are the currently documented LaoZhang gateway commitment, not the complete xAI upstream capability list. xAI documents more ratios, but values outside this page require verification in the current token group.
### How many reference images can I use?
It depends on the model: `grok-imagine-image` supports 1–4 references, while `grok-imagine-image-quality` supports 1–2. Use the standard model for three- or four-reference composition. For mask inpainting or more precise control, evaluate [GPT-Image-2](/en/api-capabilities/gpt-image-2).
### How should I store the result?
Download `url` responses promptly into your own object storage. Use `b64_json` for direct embedding or offline persistence. Do not assume temporary URLs remain available indefinitely.
## Sources and related documentation
* [xAI multi-image editing](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing) — upstream multi-image workflow and input ordering
* [xAI Grok Imagine Image model](https://docs.x.ai/developers/models/grok-imagine-image) — standard-model image input
* [xAI image generation documentation](https://docs.x.ai/developers/model-capabilities/images/generation) — upstream ratios, resolutions, batching, and response formats
* [xAI models and pricing](https://docs.x.ai/developers/pricing) — upstream model IDs and list pricing, not LaoZhang API retail pricing
* [LaoZhang Images API reference](/en/api-reference/images) — common Images API request and response structure
* [LaoZhang image generation guide](/en/api-capabilities/image-generation-guide) — cross-model selection
* [LaoZhang model pricing](https://api2.laozhang.ai/account/pricing) — current group, retail rate, and billing source of truth