Grok Imagine Image API: 2.0 Generation, Three-Image Editing, and Pricing

As of September 3, 2026, LaoZhang API provides grok-imagine-image-2.0 to eligible API-key groups. Use /v1/images/generations for text-to-image and the OpenAI-compatible multipart/form-data /v1/images/edits endpoint for one to three reference images. The current price is $0.055 per successfully returned image, and batch requests are billed by the number of outputs returned.

This is the complete LaoZhang integration guide for Grok Imagine image models. grok-imagine-image-2.0 is an exact model ID. The legacy grok-imagine-image and grok-imagine-image-quality IDs remain separate models.

Create an API key

Create a token and confirm its balance, visible models, and eligible group

Check current model pricing

Recheck the live price and call records before a large batch

Current integration scope

Item	Current `grok-imagine-image-2.0` scope
Text-to-image	JSON `POST /v1/images/generations`
Reference editing	`multipart/form-data` `POST /v1/images/edits`
Reference count	One to three; do not send a fourth image
Resolution	`1k` and `2k`
Quality	Explicit `low` or `medium` is recommended
Aspect ratios	15 fixed values; omission lets the model choose
Outputs per request	`n=1–10`
Response format	`url` or `b64_json`
Current price	$0.055 per successful output image

LaoZhang currently accepts OpenAI-compatible file uploads for editing, not the JSON image objects shown in xAI’s documentation. Four- and five-reference requests currently fail. Limit the client to three references and do not automatically retry the same over-limit request.

Choose among the three models

Model ID	Current price	Documented scope	Best for
`grok-imagine-image-2.0`	$0.055/image	1K/2K, Low/Medium, 15 fixed ratios, and up to three-reference editing	New Grok integrations, detailed generation, and reference composition
`grok-imagine-image`	$0.025/image	Lower-cost generation and the legacy multi-reference scope	Drafts, batch candidates, and cost-sensitive work
`grok-imagine-image-quality`	$0.045/image	Legacy quality model with a smaller reference limit	Existing integrations and small final-asset jobs

Test grok-imagine-image-2.0 first for new integrations. Existing workloads do not need to migrate immediately. Compare one image from each relevant model with the same prompt, ratio, and resolution before switching.

Before you call the API

Create and protect a token

Create an API key in Token Management. Keep it in a server-side environment variable, never in browser code, a public repository, or logs.

Confirm the model and price

Open model pricing, verify that the token can see grok-imagine-image-2.0, and confirm that the current price is still $0.055.

Accept one real image first

Start with n=1. Download the output and inspect its pixels, content, and call record before increasing resolution, output count, or concurrency.

Text-to-image quick start

This request creates one 2K, 16:9, Medium image:

curl "https://api2.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A cinematic lighthouse at sunrise, detailed ocean reflections, no text",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "response_format": "url"
  }'

A successful response is HTTP 200 with a readable item in data:

{
  "data": [
    {
      "url": "https://..."
    }
  ]
}

The URL is temporary. Download it into your own object storage promptly. Set response_format to b64_json when you need the image bytes in the response.

Python SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api2.laozhang.ai/v1",
    timeout=180,
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="A premium mechanical watch on dark slate, macro product photography",
    n=1,
    response_format="b64_json",
    extra_body={
        "aspect_ratio": "1:1",
        "resolution": "2k",
        "quality": "medium",
    },
)

print(response.data[0].b64_json[:40])

The OpenAI Python SDK does not expose every Grok image option as a first-class parameter. Put aspect_ratio, resolution, and quality in extra_body.

Aspect ratio, resolution, and quality

LaoZhang verified these fixed grok-imagine-image-2.0 aspect ratios:

Orientation	Supported values
Square	`1:1`
Landscape	`16:9`, `4:3`, `3:2`, `2:1`, `19.5:9`, `20:9`, `21:9`, `5:2`
Portrait	`9:16`, `3:4`, `2:3`, `1:2`, `9:19.5`, `9:20`

Omit aspect_ratio to let the model choose. Pass an explicit value when the layout must be predictable.

resolution="1k" is faster and fits drafts, thumbnails, and batch candidates;
resolution="2k" creates larger files with longer latency for final assets and cropping;
quality="low" prioritizes speed;
quality="medium" prioritizes detail;
do not send quality="high" or resolution="4k".

Successful responses do not expose the quality tier actually served. Production requests should explicitly use low or medium instead of relying on auto for cost, latency, or quality expectations.

Edit one reference image

Editing requires a file upload. Do not put an xAI-style JSON image object in the request body:

curl "https://api2.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=Change the mug to matte black. Preserve the composition, lighting, and background." \
  -F "image=@product-photo.png" \
  -F "response_format=url"

After HTTP 200, download the image and inspect the subject, color, text, and composition. Reference editing regenerates the scene; it is not pixel-level mask inpainting.

Edit with two or three references

Repeat image[] for multi-image editing. This three-image request provides the subject, scene, and style separately:

curl "https://api2.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=Place the product from image 1 in the scene from image 2, and apply the visual style from image 3. Preserve the product colors." \
  -F "image[]=@product.png" \
  -F "image[]=@scene.jpg" \
  -F "image[]=@style.jpg" \
  -F "aspect_ratio=3:2" \
  -F "response_format=url"

Upload order maps to image 1, image 2, and image 3 in the prompt. LaoZhang verified a three-reference request on api2.laozhang.ai that returned a 1248×832 JPEG on September 3, 2026.

The current limit is three references. Four- and five-image requests return an upstream service error. Count files locally and reject the request before sending it instead of retrying a known input-boundary failure.

Python SDK editing

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api2.laozhang.ai/v1",
    timeout=180,
)

with open("product.png", "rb") as image:
    response = client.images.edit(
        model="grok-imagine-image-2.0",
        image=image,
        prompt="Keep the product and change the background to a rainy neon street.",
        response_format="url",
    )

print(response.data[0].url)

The OpenAI SDK works for single-image editing. For multiple references, start with the curl form above to verify how your HTTP framework serializes repeated multipart fields.

Parameters

Parameter	Type	Required	Current behavior
`model`	string	Yes	Use `grok-imagine-image-2.0` for the new model
`prompt`	string	Yes	Describe the content, composition, style, and details that must remain
`n`	integer	No	One to ten text-to-image outputs; billed by returned image count
`aspect_ratio`	string	No	One of the 15 fixed values above; omission lets the model choose
`resolution`	string	No	Lowercase `1k` or `2k` for text-to-image
`quality`	string	No	Explicit `low` or `medium` is recommended; do not use `high`
`response_format`	string	No	`url` or `b64_json`
`image`	file	For one-image editing	One local image
`image[]`	file[]	For multi-image editing	Repeat the field, up to three files

Pricing and billing

grok-imagine-image-2.0 currently costs $0.055 per successfully returned image:

Request	Example charge
`n=1`	$0.055
`n=4`	$0.220
`n=10`	$0.550
Three-reference edit returning one result	$0.055

LaoZhang currently uses the same public price for 1K/2K and Low/Medium. LaoZhang pricing and xAI list pricing are separate billing contracts. Recheck the console before large batches and use call records as the final billing source.

Error handling

Condition	Current possible result	Client action
Invalid API key	401	Replace the token; do not retry the same credential
Missing `prompt`	400	Correct the request
`n` above 10	May return 429	Validate locally as 1–10
Unsupported aspect ratio	May return 429	Use the documented allowlist
`resolution="4k"`	May return 503	Change to `1k` or `2k`; do not treat it as a transient outage
`quality="high"`	May still return an image	Reject locally to prevent silent fallback and billing
Four or five references	500	Reduce to three; do not retry the same request

Use jittered exponential backoff for valid requests that hit 429, network errors, or clearly temporary 5xx failures. After a client timeout, check the call record before resubmitting to avoid duplicate generation and billing.

Production acceptance checklist

Generate one 1K Low image with the production token;
download the URL or decode Base64 and inspect the real MIME type and dimensions;
test the exact 2K, Medium, ratio, and n values used in production;
use distinct, non-sensitive references and verify that each subject affects the output;
enforce the three-reference edit limit;
use at least a 60-second timeout for 1K Low and 120–180 seconds for Medium and 2K;
reconcile success rate, latency, output count, and call records before increasing concurrency.

Frequently asked questions

What is the exact new model ID?

Use grok-imagine-image-2.0, including the final .0. The legacy grok-imagine-image and grok-imagine-image-quality IDs remain separate models.

Is pricing per request or per output image?

It is per successfully returned image. A successful n=10 response with ten images costs

0.550, not a single

0.055 charge.

How many reference images can I upload?

grok-imagine-image-2.0 currently accepts up to three references through multipart file upload. Four and five references are not supported.

Can I use xAI’s JSON image-editing request format?

Not currently. LaoZhang has verified OpenAI-compatible multipart uploads. JSON image objects return HTTP 400; wait for a future compatibility update if your application requires that contract.

Do 1K, 2K, Low, and Medium have the same LaoZhang price?

Yes, the current public price is $0.055 per successfully returned image. Latency and upstream cost vary by tier, so recheck the console before a large batch.

How should I store generated results?

Download URL responses promptly into your own storage. Use b64_json when the image must travel in the API response. Do not assume temporary URLs remain available indefinitely.

Grok Imagine Image 2.0 launch announcement — current price, availability, and three-image editing scope
xAI Grok Imagine Image 2.0 model — official model ID and resolution/quality pricing
xAI image generation — official ratios, resolution, quality, batching, and response formats
xAI image editing — official JSON editing contract, which differs from LaoZhang’s current multipart interface
xAI multi-image editing — upstream five-image capability, not LaoZhang’s current three-image limit
LaoZhang Images API reference — common Images API request and response structure
LaoZhang image generation guide — compare other image models
LaoZhang model pricing — current models, groups, retail prices, and call records

Getting Started

Core API

Text APIs

Video Generation APIs

Image Generation APIs

AI Understanding

Grok Imagine Image API: 2.0 Generation, Three-Image Editing, and Pricing

Create an API key

Check current model pricing

Current integration scope

Choose among the three models

Before you call the API

Text-to-image quick start

Python SDK

Aspect ratio, resolution, and quality

Edit one reference image

Edit with two or three references

Python SDK editing

Parameters

Pricing and billing

Error handling

Production acceptance checklist

Frequently asked questions

What is the exact new model ID?

Is pricing per request or per output image?

How many reference images can I upload?

Can I use xAI’s JSON image-editing request format?

Do 1K, 2K, Low, and Medium have the same LaoZhang price?

How should I store generated results?

Create an API key

Check current model pricing

​Current integration scope

​Choose among the three models

​Before you call the API

​Text-to-image quick start

​Python SDK

​Aspect ratio, resolution, and quality

​Edit one reference image

​Edit with two or three references

​Python SDK editing

​Parameters

​Pricing and billing

​Error handling

​Production acceptance checklist

​Frequently asked questions

​What is the exact new model ID?

​Is pricing per request or per output image?

​How many reference images can I upload?

​Can I use xAI’s JSON image-editing request format?

​Do 1K, 2K, Low, and Medium have the same LaoZhang price?

​How should I store generated results?

​Sources and related documentation

Current integration scope

Choose among the three models

Before you call the API

Text-to-image quick start

Python SDK

Aspect ratio, resolution, and quality

Edit one reference image

Edit with two or three references

Python SDK editing

Parameters

Pricing and billing

Error handling

Production acceptance checklist

Frequently asked questions

What is the exact new model ID?

Is pricing per request or per output image?

How many reference images can I upload?

Can I use xAI’s JSON image-editing request format?

Do 1K, 2K, Low, and Medium have the same LaoZhang price?

How should I store generated results?

Sources and related documentation