88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Image

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:

PurposeMethodEndpoint
Text-to-imagePOST/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

ModelResolutionReference imagesImages per requestBilling
grok-imagine-image1K (default) / 2K
aspect_ratio + resolution
up to 3 (data URI / public URL / local file)up to 10per image
grok-imagine-image-2.01K (default) / 2K
aspect_ratio + resolution
up to 3 (data URI / public URL / local file)up to 10per image
grok-imagine-image-quality1K (default) / 2K
aspect_ratio + resolution
up to 3 (data URI / public URL / local file)up to 10per image
grok-imagine-edit
Same as grok-imagine-image-quality
1K (default) / 2K
aspect_ratio + resolution
up to 3 (data URI / public URL / local file)up to 10per 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

Modelqualityresponse_format
grok-imagine-imageNot supportedb64_json / url
grok-imagine-image-2.0low / medium / autob64_json / url
grok-imagine-image-qualityNot supportedb64_json / url
grok-imagine-editNot supportedb64_json / url
  • All four models support both text-to-image and image editing.
  • grok-imagine-edit and grok-imagine-image-quality are the same model and produce the same results.
  • The quality parameter only applies to grok-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/json

Aspect ratio and resolution

  • aspect_ratio: see the capability table above. Defaults to auto, 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) or 2k. 4K is not supported.

Output pixels for each level (the same for all four models):

Ratio1K2K
1:11024x10242048x2048
16:91280x7202816x1584
9:16720x12801584x2816
4:31152x8642368x1776
3:4864x11521776x2368
3:21248x8322496x1664
2:3832x12481664x2496
2:11408x7042912x1456
1:2704x14081456x2912
19.5:91248x5762912x1344
9:19.5576x12481344x2912
20:91280x5763200x1440
9:20576x12801440x3200
21:91568x6723136x1344
5:21600x6403200x1280
  • 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 example 1024x1024), which is converted automatically: a long side of 1024 or less maps to 1k, anything larger maps to 2k, and the closest supported aspect ratio is used. The returned pixels therefore may not match the requested size. Both 1536x1024 and 1792x1024 are output at 2k.
  • If you pass both size and aspect_ratio / resolution, aspect_ratio / resolution take 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

ParameterTypeRequiredDescription
modelstringyesModel name.
promptstringyesDescription of the image; must not be empty. We recommend keeping it to a few thousand characters at most.
aspect_ratiostringnoAspect ratio, default auto.
resolutionstringno1k (default) or 2k.
nintegernoNumber of images, 1 to 10, default 1.
response_formatstringnob64_json (default) or url. With url, an 88API image link is returned.
qualitystringnogrok-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

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 image as an array, and do not pass image and images together.
  • 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 with aspect_ratio and resolution.

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

  • mask inpainting 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

ScenarioHTTPMessage returned
Calling the chat or Responses endpoint400<模型> 是生图模型,不支持 <接口> 接口。请改用: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 ratio400不支持的图片比例。支持:… (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 upload400上游拒绝了请求参数(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 downloaded400An error message about the reference image
More than 3 reference images502Upstream request failed
Content moderation failure400图片生成未通过内容安全审核,请修改提示词或参考素材后重试。 (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.