Grok Image Model API
Text-to-image and image editing endpoints, aspect ratios, resolutions, reference images and errors for the Grok Imagine image models (grok-imagine-image, 2.0, quality, edit).
Scope
This page covers the Grok Imagine image models. For video models, see Grok Video API.
Choosing an endpoint
Grok image models use the OpenAI Images-compatible endpoints:
| Purpose | Method | Endpoint |
|---|---|---|
| Text-to-image | POST | /v1/images/generations |
| Image editing (image-to-image) | POST | /v1/images/edits |
/v1/chat/completions and /v1/responses are not supported. Reference images can only be passed through /v1/images/edits; reference images included in /v1/images/generations are ignored.
Models and capabilities
| Model | Resolution | Reference images | Images per request | Billing |
|---|---|---|---|---|
grok-imagine-image | 1K (default) / 2Kaspect_ratio + resolution | up to 3 (data URI / public URL / local file) | up to 10 | per image |
grok-imagine-image-2.0 | 1K (default) / 2Kaspect_ratio + resolution | up to 3 (data URI / public URL / local file) | up to 10 | per image |
grok-imagine-image-quality | 1K (default) / 2Kaspect_ratio + resolution | up to 3 (data URI / public URL / local file) | up to 10 | per image |
grok-imagine-editSame as grok-imagine-image-quality | 1K (default) / 2Kaspect_ratio + resolution | up to 3 (data URI / public URL / local file) | up to 10 | per image |
Supported aspect ratios: auto (default) / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 2:1 / 1:2 / 19.5:9 / 9:19.5 / 20:9 / 9:20 / 21:9 / 5:2
| Model | quality | response_format |
|---|---|---|
grok-imagine-image | Not supported | b64_json / url |
grok-imagine-image-2.0 | low / medium / auto | b64_json / url |
grok-imagine-image-quality | Not supported | b64_json / url |
grok-imagine-edit | Not supported | b64_json / url |
- All four models support both text-to-image and image editing.
grok-imagine-editandgrok-imagine-image-qualityare the same model and produce the same results.- The
qualityparameter only applies togrok-imagine-image-2.0. - Billed by the number of images successfully returned, regardless of resolution or the number of reference images.
The model list returned in the console is the authoritative list of available models.
Authentication
Authorization: Bearer $API_KEY
Content-Type: application/jsonAspect ratio and resolution
aspect_ratio: see the capability table above. Defaults toauto, which lets the model choose the framing based on the prompt, so the same prompt may not always produce the same aspect ratio. If you need a fixed size, pass it explicitly.resolution:1k(default) or2k. 4K is not supported.
Output pixels for each level (the same for all four models):
| Ratio | 1K | 2K |
|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 |
| 16:9 | 1280x720 | 2816x1584 |
| 9:16 | 720x1280 | 1584x2816 |
| 4:3 | 1152x864 | 2368x1776 |
| 3:4 | 864x1152 | 1776x2368 |
| 3:2 | 1248x832 | 2496x1664 |
| 2:3 | 832x1248 | 1664x2496 |
| 2:1 | 1408x704 | 2912x1456 |
| 1:2 | 704x1408 | 1456x2912 |
| 19.5:9 | 1248x576 | 2912x1344 |
| 9:19.5 | 576x1248 | 1344x2912 |
| 20:9 | 1280x576 | 3200x1440 |
| 9:20 | 576x1280 | 1440x3200 |
| 21:9 | 1568x672 | 3136x1344 |
| 5:2 | 1600x640 | 3200x1280 |
- 1K output is JPEG and 2K output is PNG; this cannot be changed with
output_format. - You can also use the OpenAI-style
size(for example1024x1024), which is converted automatically: a long side of 1024 or less maps to1k, anything larger maps to2k, and the closest supported aspect ratio is used. The returned pixels therefore may not match the requestedsize. Both1536x1024and1792x1024are output at2k. - If you pass both
sizeandaspect_ratio/resolution,aspect_ratio/resolutiontake precedence.
Text-to-image
curl https://api.88api.ai/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image",
"prompt": "A Tokyo street under neon lights on a rainy night, cinematic, realistic photography",
"aspect_ratio": "16:9",
"resolution": "2k",
"n": 1
}'Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | yes | Model name. |
prompt | string | yes | Description of the image; must not be empty. We recommend keeping it to a few thousand characters at most. |
aspect_ratio | string | no | Aspect ratio, default auto. |
resolution | string | no | 1k (default) or 2k. |
n | integer | no | Number of images, 1 to 10, default 1. |
response_format | string | no | b64_json (default) or url. With url, an 88API image link is returned. |
quality | string | no | grok-imagine-image-2.0 only: low, medium, auto (default; low for generation and medium for editing). medium is slower to generate. |
Parameters such as style, seed, negative_prompt, background, output_format and stream are ignored.
Response example
{
"created": 1760000000,
"data": [
{ "b64_json": "/9j/4AAQ...", "mime_type": "image/jpeg" }
]
}The response does not include revised_prompt.
Image editing
JSON request (recommended, supports multiple reference images)
Use image for a single reference image and the images array for multiple reference images, up to 3:
curl https://api.88api.ai/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image-quality",
"prompt": "Place the person from the first image into the scene of the second image, keeping their appearance unchanged",
"images": [
"data:image/png;base64,...",
"https://example.com/scene.jpg"
],
"resolution": "2k"
}'- Reference images can be Data URIs or publicly downloadable URLs. Base64 data must include the
data:image/...;base64,prefix. - JPG, PNG and WebP are supported; GIF and BMP are not.
- Do not pass
imageas an array, and do not passimageandimagestogether. - Reference images are numbered in the order they are passed, so your prompt can refer to them as "the first image", "the second image" and so on.
- If you omit the aspect ratio, the output follows the aspect ratio of the first reference image, and the resolution defaults to
1k. You can override both withaspect_ratioandresolution.
multipart upload (single image)
Local files can also be uploaded with multipart, but only one image per request, and each file must be at most 20 MB:
curl https://api.88api.ai/v1/images/edits \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-imagine-image" \
-F "image=@input.png" \
-F "prompt=Change the background to a sunset at the beach" \
-F "aspect_ratio=1:1"Use a JSON request if you need multiple reference images.
Limitations
maskinpainting is not supported; any mask you pass is ignored.- Streaming output and asynchronous result retrieval are not supported.
- Output images carry C2PA Content Credentials (marked as AI-generated) and have no visible watermark.
Common errors
| Scenario | HTTP | Message returned |
|---|---|---|
| Calling the chat or Responses endpoint | 400 | <模型> 是生图模型,不支持 <接口> 接口。请改用:POST /v1/images/generations, POST /v1/images/edits (<model> is an image model and does not support the <endpoint> endpoint; use the image endpoints instead) |
| Unsupported aspect ratio | 400 | 不支持的图片比例。支持:… (unsupported aspect ratio, followed by the supported values) |
Unsupported resolution (for example 4k) | 400 | 不支持的图片分辨率。resolution 仅支持 1k 或 2k,请使用小写格式。 (unsupported resolution; only lowercase 1k or 2k is accepted) |
n outside 1 to 10, empty prompt, both image and images passed, or multiple images in a multipart upload | 400 | 上游拒绝了请求参数(invalid-argument),请检查模型名、调用接口和请求参数 (the upstream rejected the request parameters; check the model name, endpoint and parameters) |
| Unsupported reference image format, Base64 missing its prefix, or a URL that cannot be downloaded | 400 | An error message about the reference image |
| More than 3 reference images | 502 | Upstream request failed |
| Content moderation failure | 400 | 图片生成未通过内容安全审核,请修改提示词或参考素材后重试。 (the image did not pass the content safety review; revise the prompt or reference material and try again) |
Failed requests like these are not charged.