Grok Imagine API Documentation

xAI's image generation models — text-to-image and image editing, called with one APIMODELS key and no separate xAI account.

Authentication

Authorization: Bearer YOUR_API_KEY

Models & pricing

Model	model	Price	Notes
Grok Imagine Image	grok-imagine/grok-imagine-image	$0.03/image	Grok Imagine standard tier, text-to-image + image edit (synchronous, 19s median)
Grok Imagine Image Pro	grok-imagine-pro/grok-imagine-image-pro	$0.0800-$0.1200/image	Pro detail, native 1K/2K (2K default), text-to-image + multi-image edit (up to 3 refs, no extra charge)
Grok Imagine Image 2.0	grok-imagine-image-2.0	$0.0300-$0.0600/image	New generation: four tiers by resolution x quality (1K low $0.03, 2K low $0.04, 1K medium $0.045, 2K medium $0.06). Legible headline and small-print typography, up to 3 reference images fused, fourteen aspect ratios including the four ultra-wide ones. Note: no transparent background or cutout — ask for alpha and it paints the checkerboard as pixels.

Code examples

# Step 1: Create task (text-to-image)
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/grok-imagine-image",
    "prompt": "A cute cat wearing a space helmet, digital art",
    "aspect_ratio": "1:1",
    "n": 1
  }'

# Image editing (one reference image; aspect_ratio is ignored here)
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/grok-imagine-image",
    "prompt": "Replace the cat with a golden retriever",
    "image_url": "https://example.com/cat.png"
  }'

# Multi-image editing (up to 3 references, Pro only)
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-pro/grok-imagine-image-pro",
    "prompt": "Put the dog from <IMAGE_1> into the room from <IMAGE_0>",
    "image_urls": ["https://example.com/room.png", "https://example.com/dog.png"],
    "resolution": "2k"
  }'

# Step 2: Poll status
curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Request parameters

Field	Required	Type	Description
model	Yes	string	grok-imagine/grok-imagine-image / grok-imagine-pro/grok-imagine-image-pro / grok-imagine-image-2.0（新一代，$0.03 起）
prompt	Yes	string	Text description or editing instructions
image_url	No	string	Reference image URL or base64, for image editing
image_urls	No	string[]	grok-imagine-pro only: multiple reference images (up to 3, at no extra charge — price depends on resolution only). Refer to them as <IMAGE_0>, <IMAGE_1> in the prompt. More than 3 returns an error rather than silently dropping any.
image_base64	No	string	Base64-encoded reference image, for image editing
resolution	No	string	Either 1k or 2k; defaults to 2k. On grok-imagine-pro it is tiered ($0.08 at 1k, $0.12 at 2k). Measured output: 2048x2048 for a square 2K request, 2816x1584 at 16:9. Note that passing an OpenAI-style size without an explicit resolution derives the tier from that size.
aspect_ratio	No	string	grok-imagine and grok-imagine-pro: 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, auto (default 1:1; ignored when a reference image is provided).
quality	No	string	grok-imagine-image-2.0 only: low or medium, defaulting to medium. This field selects your price tier — combined with resolution it gives the four tiers ($0.03 / $0.04 / $0.045 / $0.06). The other Grok image models do not accept it.
n	No	integer	Number of images: 1-10 (default 1; grok-imagine and grok-imagine-pro only support 1)
callback_url	No	string	Webhook URL called when task completes

Notes

grok-imagine: a reference image may be a public URL or base64 (one image); aspect_ratio is ignored when one is supplied — the output follows the input image's ratio
grok-imagine-pro: up to 3 reference images (image_urls), referenced as <IMAGE_0>, <IMAGE_1> in the prompt
Mask inpainting has been removed: it belonged to the retired channel, not to the model

Try it in the Playground

FAQ

What is the endpoint and model ID for the Grok Imagine API?

POST https://api.apimodels.app/v1/images/generations with an Authorization: Bearer header. The model field takes grok-imagine-image-2.0 (newest generation, from $0.03), grok-imagine-image-pro (high detail, 1K $0.08 / 2K $0.12), or grok-imagine-image (standard, $0.03). One APIMODELS key covers all three — you do not need an xAI account of your own.

How much does the Grok image API cost per image?

grok-imagine-image-2.0 is priced by resolution × quality: 1K low $0.03, 2K low $0.04, 1K medium $0.045, 2K medium $0.06 — all 25% below xAI list, and 2K low 33% below. grok-imagine-image is $0.03 per image (~4s). grok-imagine-image-pro is tiered by resolution: 1K $0.08, 2K $0.12. Reference images never cost extra on any of them, and failed calls are never charged.

Does Grok Imagine follow my aspect_ratio when I pass a reference image?

It depends on the model. On grok-imagine-image-2.0, omitting aspect_ratio makes the output follow the first input image, but an explicit value is honoured — including the four ultra-wide ratios 19.5:9, 9:19.5, 20:9 and 9:20, which we verified one at a time against the live channel. On the older grok-imagine-image and Pro channels, a supplied reference image makes aspect_ratio ignored and the output follows the input ratio.

Does the Grok image API support mask-based inpainting or transparent backgrounds?

Neither. There is no mask parameter on any of these models — to change one region, pass the original image and describe the change in words. And none of them produce an alpha channel: ask grok-imagine-image-2.0 for a transparent background and it paints the grey-and-white checkerboard as ordinary pixels, returning an RGB PNG that only looks like a cutout in a thumbnail. Run a dedicated background-removal step instead.

Models on this page

Grok Imagine Image 2.0 · from $0.03