Grok Imagine API: images and edits, $0.055

Grok Imagine Image 2.0 is xAI’s current image model. Text-to-image and reference editing both use the OpenAI-compatible Images endpoints, and one request can return several images. On LaoZhang API the model ID is grok-imagine-image-2.0, and each image costs $0.055 at 1K or 2K, with no xAI account needed.

What grok-imagine-image-2.0 supports

Item	Details
Model ID	`grok-imagine-image-2.0`, including the final `.0`
Price	$0.055 per image at `1k` or `2k` and `low` or `medium`, for both generation and editing, billed per successfully returned image
Account	No xAI account needed, only a LaoZhang API key
Token group and billing mode	`default`; Usage first (recommended) or Per-call
Endpoints	Text-to-image: JSON `POST /v1/images/generations`; reference editing: multipart `POST /v1/images/edits`
Concurrency and rate limits	No platform limit on concurrency and no throttling; a `429` comes from upstream capacity, see Concurrency and 429
Failed requests	Non-200 responses with no image aren’t billed; check the call log after a timeout, see Billing and failure rules

xAI prices by resolution and quality; on LaoZhang API each of these tiers is $0.055 per image, with no input charge for edits:

1K medium or 2K low: $0.06 at xAI
2K medium: $0.08 at xAI
Edits: xAI adds $0.01 per input image

The model is made by xAI. Public pricing as of September 24, 2026, verified on October 14, 2026; see the model and pricing catalog. xAI’s prices are from its model page, verified October 13, 2026.

A cinematic lighthouse at sunrise with ocean reflections, generated by Grok Imagine Image 2.0 — Output of the generate example below: 2K, 16:9, medium

Parameters and limits

Parameter	Values
References per edit	1–3
Resolution	`1k` or `2k`
Quality	`low` or `medium`, set explicitly
Aspect ratios	15 fixed values; omit to let the model choose
Images per request	`n` from 1 to 10, billed per returned image
Response format	`url` or `b64_json`

Editing accepts OpenAI-compatible file uploads, not the JSON image objects shown in xAI’s documentation. Requests with four or five references fail, so enforce the three-image limit in your client and don’t retry an over-limit request.

Choose a Grok Imagine model

Model ID	Scope	Best for
`grok-imagine-image-2.0`	1K/2K, `low`/`medium`, 15 fixed ratios, edits with 1–3 references	New integrations, detailed images, and reference composition
`grok-imagine-image`	Withdrawn on October 30, 2026	Use `grok-imagine-image-2.0` instead
`grok-imagine-image-quality`	Earlier quality model with a smaller reference limit	Existing integrations and small final-asset jobs

grok-imagine-image: withdrawn on October 30, 2026; calls now return 503. Change model to grok-imagine-image-2.0; aspect_ratio and multi-reference edits work the same way. See the withdrawal notice.
grok-imagine-image-quality: xAI announced the retirement of this model from November 2, 2026, with its requests served by grok-imagine-image-2.0 at low quality (xAI migration guide). As of November 3, 2026, it is still callable on LaoZhang API at $0.045 per successfully returned image, billed the same way as 2.0. For new integrations, use 2.0 and set quality explicitly.

Before you call the API

Create and protect an API key

Create a key in the default group in Token management and set Billing mode (计费模式) to Usage first (按量优先, recommended) or Per-call (按次计费). A Usage first key can call both per-call and usage-based models; a Per-call key calls only per-call models.Keep the key in a server-side environment variable, never in browser code, a public repository, or logs.

Confirm model access and price

In Models and pricing, check that the key can use grok-imagine-image-2.0 and review the current price.

Set up your environment

Export the key and install the OpenAI Python SDK, which the Python examples use:

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
python3 -m pip install openai

Generate and edit images

Generate an image

This request creates one 2K, 16:9 image at medium quality and writes the response to grok-generation.json:

curl --fail-with-body "https://api.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"
  }' \
  -o grok-generation.json

A successful response returns HTTP 200 with one item in data:

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

Save the result

The URL is temporary, so download the image right away. Save this script as save_images.py. It writes every image in a response to disk, whether the response contains url or b64_json, and picks the file extension from the image data:

save_images.py

import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"No image in {response_file}: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # Drop an optional data:image/...;base64, prefix and restore missing padding.
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"Saved {path}")

python3 save_images.py grok-generation.json grok-lighthouse

The script prints a line such as Saved grok-lighthouse-1.jpg. Open the file and check the subject, text, and composition. To receive the image bytes in the response instead of a URL, set response_format to b64_json.

Generate with the Python SDK

The OpenAI Python SDK doesn’t expose every Grok image option as a named parameter, so pass aspect_ratio, resolution, and quality in extra_body. This example requests Base64 output and saves the decoded image:

import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.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",
    },
)

value = response.data[0].b64_json.split(",", 1)[-1]
image = base64.b64decode(value + "=" * (-len(value) % 4))
extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"grok-watch.{extension}")
output.write_bytes(image)
print(f"Saved {output}")

Edit one reference image

Editing requires a file upload. Put a local product-photo.png in the current directory, then run:

curl --fail-with-body "https://api.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" \
  -o grok-edit.json

python3 save_images.py grok-edit.json grok-edit

Reference editing regenerates the scene; it isn’t pixel-level mask inpainting. Check the subject, color, text, and composition in the saved image.

Edit with two or three references

Repeat the image[] field for each reference. This request supplies the subject, the scene, and the style as three separate files:

curl --fail-with-body "https://api.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" \
  -o grok-multi-edit.json

python3 save_images.py grok-multi-edit.json grok-multi-edit

Upload order maps to image 1, image 2, and image 3 in the prompt. A successful request returns one image; with aspect_ratio=3:2, expect a landscape result such as 1248×832.

Edit with the Python SDK

The OpenAI SDK works for single-image edits. This example returns a URL and downloads the image immediately:

import os
import urllib.request
from pathlib import Path

from openai import OpenAI

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

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

with urllib.request.urlopen(response.data[0].url, timeout=120) as download:
    image = download.read()
extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"grok-sdk-edit.{extension}")
output.write_bytes(image)
print(f"Saved {output}")

For multiple references, start with the cURL form above to confirm how your HTTP client serializes repeated multipart fields.

Aspect ratio, resolution, and quality

grok-imagine-image-2.0 accepts these 15 fixed aspect ratios:

Orientation	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, or pass a value when the layout must be predictable.

resolution="1k" is faster and suits drafts, thumbnails, and batch candidates.
resolution="2k" produces larger files with longer latency, for final assets and cropping.
quality="low" favors speed; quality="medium" favors detail.
Don’t send quality="high" or resolution="4k".

Responses don’t report which quality tier was used. Set quality to low or medium explicitly rather than relying on auto, so latency and output quality stay predictable.

Pricing and billing

Billing counts the images a request actually returns:

Request	Billed as
`n=1`, one image returned	1 image
`n=4`, four images returned	4 images
`n=10`, ten images returned	10 images ($0.55 at the current price)
Three-reference edit returning one image	1 image

LaoZhang API charges the same price for 1k and 2k and for low and medium. The comparison with xAI’s prices by resolution and quality is in the price note at the top of this page. Check the console before a large batch, and treat call records as the final billing source.

Parameters, errors, and launch checks

Parameters

Parameter	Type	Required	Behavior
`model`	string	Yes	`grok-imagine-image-2.0`
`prompt`	string	Yes	Content, composition, style, and details that must stay the same
`n`	integer	No	1–10 text-to-image outputs; each returned image is billed
`aspect_ratio`	string	No	One of the 15 values above; omit to let the model choose
`resolution`	string	No	Lowercase `1k` or `2k` for text-to-image
`quality`	string	No	`low` or `medium`; don’t send `high`
`response_format`	string	No	`url` or `b64_json`
`image`	file	For one-image edits	One local image
`image[]`	file	For multi-image edits	Repeat the field for up to three files

Error handling

Condition	Possible result	What to do
Invalid API key	401	Replace the key; don’t retry with the same credential
Missing `prompt`	400	Fix the request
`n` above 10	May return 429	Validate `n` locally as 1–10
Unsupported aspect ratio	May return 429	Use the values listed above
`resolution="4k"`	May return 503	Use `1k` or `2k`; this isn’t a temporary outage
`quality="high"`	May still return an image	Reject it locally to avoid a silent fallback and charge
Four or five references	500	Reduce to three; don’t retry the same request

Retry valid requests that hit 429, network errors, or clearly temporary 5xx errors with jittered exponential backoff. After a client timeout, check the call record before you resubmit, so you don’t generate and pay for the same image twice.

Before you go to production

Generate one 1k, low image with the production key.
Save the result and check its real format and dimensions.
Test the exact resolution, quality, aspect ratio, and n values you plan to use.
For edits, use distinct, non-sensitive references and confirm that each one affects the output.
Enforce the three-reference limit in your client.
Set a timeout of at least 60 seconds for 1k low requests and 120–180 seconds for medium or 2k.
Reconcile success rate, latency, output count, and call records before raising concurrency.

Frequently asked questions

Can I call Grok Imagine without an xAI account?

Yes. You need only a LaoZhang API key, not an xAI account. Generation and editing both use the OpenAI-compatible Images endpoints, billed per successfully returned image.

What is the exact model ID?

Use grok-imagine-image-2.0, including the final .0. The earlier grok-imagine-image was withdrawn on October 30, 2026; grok-imagine-image-quality is a separate earlier model that xAI announced it would retire from November 2; use 2.0 for new integrations.

Am I billed per image? Do resolution and quality change the price?

Per successfully returned image. 1k, 2k, low, and medium currently share one per-image price; see Pricing and billing for examples. Latency differs by tier, so plan timeouts accordingly: on October 14, 2026 the quick-start prompt took 16 s at 1K low and 71 s at 2K medium, and each call was logged at $0.055.

Lighthouse on a rocky coast at sunrise with sunlight reflecting on the sea, generated by Grok Imagine Image 2.0 at 1K low — 1K, low, 16:9: 16 s, $0.055

Lighthouse on a rocky coast at sunrise with detailed clouds and waves, generated by Grok Imagine Image 2.0 at 2K medium — 2K, medium, 16:9: 71 s, $0.055

A request that returns a non-200 error and no image isn’t billed per image. A client timeout isn’t the same as a failure, though: the server may have finished and charged for the image, so check the call record before you resend. Call records are the final billing source.

Can I edit with xAI’s JSON format or send four or five references?

No to both. Editing accepts only multipart file uploads, with up to three references, as the table at the top of this page shows. xAI’s JSON image objects return HTTP 400. xAI’s documentation says the OpenAI SDK’s images.edit() doesn’t work for Grok editing; that applies to xAI’s own JSON-only API. On LaoZhang API, images.edit() works for single-image edits, as shown in Edit with the Python SDK. For several references, start with the cURL image[] form.

What aspect ratio does an edit return?

According to xAI, an edit without aspect_ratio follows the first reference image’s aspect ratio. To fix the frame, add aspect_ratio to the edit request; the three-reference example uses aspect_ratio=3:2 and returns a 1248×832 image.

Can I keep editing the previous result?

Yes. Download the previous result, upload it as the image, and describe only this round’s change in the prompt, such as “Keep everything the same and add a gold border.” Each round is a new edit request, billed for the images it returns.

How should I store generated images?

Download URL results promptly into your own storage; xAI also describes the returned URLs as temporary. Use b64_json when the image must arrive inside the API response.

Grok Imagine Image 2.0 launch announcement: availability and the three-reference editing scope
xAI Grok Imagine Image 2.0 model: official model ID and upstream pricing by resolution and quality
xAI image generation: official ratios, resolution, quality, batching, and response formats
xAI image editing: the upstream JSON editing format, which differs from LaoZhang API’s multipart interface
xAI multi-image editing: how to write multi-image edit prompts; LaoZhang API accepts up to three references per edit
Images API reference: shared request and response structure
Choose an image generation API: compare Grok Imagine with other image models
Models and pricing in the console: models, groups, prices, and call records for your account

Get started

Image Generation & Editing APIs

Video Generation APIs

Text APIs

Multimodal & Audio APIs

Grok Imagine API: images and edits, $0.055

What grok-imagine-image-2.0 supports

Parameters and limits

Choose a Grok Imagine model

Before you call the API

Generate and edit images

Generate an image

Save the result

Generate with the Python SDK

Edit one reference image

Edit with two or three references

Edit with the Python SDK

Aspect ratio, resolution, and quality

Pricing and billing

Parameters, errors, and launch checks

Parameters

Error handling

Before you go to production

Frequently asked questions

Can I call Grok Imagine without an xAI account?

What is the exact model ID?

Am I billed per image? Do resolution and quality change the price?

Can I edit with xAI’s JSON format or send four or five references?

What aspect ratio does an edit return?

Can I keep editing the previous result?

How should I store generated images?

​What grok-imagine-image-2.0 supports

​Parameters and limits

​Choose a Grok Imagine model

​Before you call the API

​Generate and edit images

​Generate an image

​Save the result

​Generate with the Python SDK

​Edit one reference image

​Edit with two or three references

​Edit with the Python SDK

​Aspect ratio, resolution, and quality

​Pricing and billing

​Parameters, errors, and launch checks

​Parameters

​Error handling

​Before you go to production

​Frequently asked questions

​Can I call Grok Imagine without an xAI account?

​What is the exact model ID?

​Am I billed per image? Do resolution and quality change the price?

​Can I edit with xAI’s JSON format or send four or five references?

​What aspect ratio does an edit return?

​Can I keep editing the previous result?

​How should I store generated images?

​Sources and related documentation

What grok-imagine-image-2.0 supports

Parameters and limits

Choose a Grok Imagine model

Before you call the API

Generate and edit images

Generate an image

Save the result

Generate with the Python SDK

Edit one reference image

Edit with two or three references

Edit with the Python SDK

Aspect ratio, resolution, and quality

Pricing and billing

Parameters, errors, and launch checks

Parameters

Error handling

Before you go to production

Frequently asked questions

Can I call Grok Imagine without an xAI account?

What is the exact model ID?

Am I billed per image? Do resolution and quality change the price?

Can I edit with xAI’s JSON format or send four or five references?

What aspect ratio does an edit return?

Can I keep editing the previous result?

How should I store generated images?

Sources and related documentation