Grok Imagine 2 API Image Generation and Editing

LaoZhang API now provides grok-imagine-image and grok-imagine-image-quality for text-to-image generation, 1K/2K output, batches of up to 10 images, and natural-language editing with reference images. Current LaoZhang API per-image pricing is $0.02 for the standard model and $0.045 for the quality model. Confirm the available token group, current price, and recorded charge in the console.

This guide uses “Grok Imagine 2” as the product label for the current Grok Imagine image generation. The request model IDs do not contain 2: use grok-imagine-image or grok-imagine-image-quality.

Create an API key

Create a token and confirm its model group, balance, and billing mode

Read the launch announcement

Check the publication date, scope, pricing, and current status

Choose a model

Model ID	Current LaoZhang price	Resolution	Reference-image boundary	Best for
`grok-imagine-image`	$0.02/image	1K / 2K	1–4 references verified on LaoZhang	Everyday assets, drafts, fast iteration, and multi-image composition
`grok-imagine-image-quality`	$0.045/image	1K / 2K	LaoZhang supports 1–2 references	Final assets, marketing work, detail, and reference editing

LaoZhang API currently bills by the number of generated images, so n=4 is four image charges. 1K and 2K currently have the same LaoZhang price. xAI list pricing and LaoZhang API pricing are separate billing contracts; use the console and latest announcement for current LaoZhang rates.

Current integration scope

Item	Current LaoZhang documented scope
Text-to-image endpoint	`POST /v1/images/generations`
Reference-image editing	`POST /v1/images/edits`
Aspect ratios	`1:1`, `16:9`, `9:16`, `4:3`, `3:4`
Resolution	`1k`, `2k`
Images per request	`n` from 1 through 10
Standard-model references	`grok-imagine-image` supports 1–4 files
Quality-model references	`grok-imagine-image-quality` supports 1–2 files
Response format	`url` or `b64_json`
Outside the current commitment	4K, mask inpainting, reproducible `seed`, arbitrary pixel sizes

xAI documents additional aspect ratios upstream. This LaoZhang page commits only to the five values above. Treat any other ratio as unverified on the current gateway until a later documentation or console update expands the scope.

n=10 means up to ten generated output images in one request. It is not a ten-reference input limit; reference counts are model- and route-specific.

Prerequisites

Create and protect an API key

Create a key in Token Management. Never expose it in browser code, a public repository, or logs.

Confirm model and price

Check the model pricing page for the target token group and current rate. A new announcement does not retroactively change earlier charges.

Run a one-image acceptance test

Use the production token, prompt, and parameters to generate one image. Check the HTTP status, data array, actual dimensions, downloaded file, and call log before increasing n or concurrency.

Text-to-image quick start

Use the OpenAI-compatible Images endpoint:

curl https://api2.laozhang.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "A minimalist technology product poster, deep blue background, crisp typography, studio lighting",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "response_format": "url"
  }'

A successful response is HTTP 200 with one readable image item in data. When requesting url, download the file promptly instead of treating a temporary URL as permanent storage.

Python SDK

import os
from openai import OpenAI

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

response = client.images.generate(
    model="grok-imagine-image-quality",
    prompt="A premium skincare product on travertine, soft morning light",
    n=2,
    extra_body={
        "aspect_ratio": "4:3",
        "resolution": "2k",
        "response_format": "url",
    },
)

for index, image in enumerate(response.data, start=1):
    print(index, image.url)

The Python OpenAI SDK does not expose every xAI extension as a first-class parameter. Passing aspect_ratio, resolution, and response_format through extra_body is the safest portable form.

Reference-image editing

Use /v1/images/edits whenever the task depends on an existing subject, composition, palette, or style. The current LaoZhang compatibility route accepts multipart/form-data file uploads. Do not place a reference-image field in /v1/images/generations and treat HTTP 200 alone as proof that editing occurred.

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

For multi-image composition, submit image[] repeatedly. Upload order maps to “image 1 / image 2 / image 3 / image 4” in the prompt. LaoZhang currently provides these model-specific ranges:

Model	References supported by LaoZhang	Recommended use
`grok-imagine-image`	1–4	Three- or four-reference composition and routine multi-image work
`grok-imagine-image-quality`	1–2	Detailed single-image edits and two-image fusion

This is the currently runnable four-reference form for the standard model:

curl https://api2.laozhang.ai/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=grok-imagine-image" \
  -F "prompt=Place the product from image 1 in the scene from image 2, use the warm film style from image 3, and preserve the brand colors from image 4." \
  -F "image[]=@product.png" \
  -F "image[]=@scene.jpg" \
  -F "image[]=@style.jpg" \
  -F "image[]=@brand-reference.png"

Requests above the current reference limit return HTTP 400. Limit Quality to two references. For three- or four-reference composition, use grok-imagine-image instead of retrying the same over-limit request.

The first reference affects the edit output’s aspect ratio. A 1280×720 first image produced 1280×720, while moving a 1200×1200 source to the first position produced 1024×1024. Depend on the first image’s orientation, not on exact pixel equality.

Reference editing is not mask-based inpainting. The model reconstructs an output from natural-language instructions. Manually verify identity, logos, text, and exact geometry; one successful sample is not a pixel-perfect fidelity guarantee.

Parameters

Parameter	Type	Required	Current values and behavior
`model`	string	Yes	`grok-imagine-image` or `grok-imagine-image-quality`
`prompt`	string	Yes	Describe content, composition, style, and what must remain unchanged
`n`	integer	No	1–10 output images; billed by generated output count, not the number of references
`aspect_ratio`	string	No	Five documented text-to-image values: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`
`resolution`	string	No	Lowercase `1k` or `2k` for text-to-image; `4k` is not currently supported
`response_format`	string	No	`url` or `b64_json`
`image` / `image[]`	file	For editing	Use `image` for one file and repeat `image[]` for multi-image edits. Standard supports 1–4; Quality supports 1–2

Use the following table to validate orientation and resolution class. Read the actual output dimensions in production rather than hard-coding inferred pixel sizes:

Ratio	1K orientation	2K orientation	Common uses
`1:1`	Square	Square	Avatars, product images, social cards
`16:9`	Landscape	Landscape	Covers, presentations, thumbnails
`9:16`	Portrait	Portrait	Shorts covers and mobile stories
`4:3`	Landscape	Landscape	Product imagery and presentations
`3:4`	Portrait	Portrait	Portraits and posters

Migrating from another Images API

Do not replace only the model name if the existing code uses size: "1536x1024" or quality: "high". The current Grok Imagine route uses aspect_ratio plus resolution for the canvas and separate model IDs for standard and quality output.

Existing behavior	Grok Imagine 2 migration action
`size: "1536x1024"`	Map to a documented aspect ratio. Note that `3:2` is not among LaoZhang’s current five committed values, so choose a documented ratio or test first
`quality: "high"`	Select `grok-imagine-image-quality`
Parser expects `b64_json`	Set `response_format: "b64_json"`, or read `data[].url`
Reference image sent to generations	Move it to `/v1/images/edits` as a file upload
Workflow depends on mask or `seed`	Keep the original model or redesign the workflow; these are not currently committed features

Production acceptance and errors

Generate one 1K 1:1 image with each model to verify token group, price, and response parsing.
Test the target ratio and 2K next; read actual dimensions and retain the original response.
Use distinct, non-sensitive references and confirm that every subject and identifying feature appears in the entity. HTTP 200 alone does not prove multi-image use.
Do not retry an over-limit reference request: reduce Quality to two references or Standard to four.
resolution=4k can currently return HTTP 503, but this is an unsupported parameter rather than a transient outage; use 1k or 2k.
Apply jittered exponential backoff to 429 and network errors. Correct other 400, 401, or 403 request/account problems before retrying.
After a client timeout, check the call log before resubmitting to avoid duplicate charges.

HTTP 200 proves only that the request was processed. It does not prove that the requested ratio, reference, or business constraint was satisfied. Acceptance must inspect dimensions, content, returned item count, and the console charge.

Frequently asked questions

What are the Grok Imagine 2 model IDs?

Use grok-imagine-image or grok-imagine-image-quality. Do not add 2; grok-imagine-2-image is not a model ID documented on this page.

Which model should I choose?

Start with grok-imagine-image at $0.02/image for routine assets and batch drafts. Compare the same prompt, ratio, and resolution on grok-imagine-image-quality at $0.045/image when final detail or reference editing matters.

Do 1K and 2K cost the same?

Yes under the current LaoZhang launch pricing. Both resolution classes use the same per-image rate for the selected model. Recheck the console before a large batch because pricing can change.

Why does this page list only five aspect ratios?

They are the currently documented LaoZhang gateway commitment, not the complete xAI upstream capability list. xAI documents more ratios, but values outside this page require verification in the current token group.

How many reference images can I use?

It depends on the model: grok-imagine-image supports 1–4 references, while grok-imagine-image-quality supports 1–2. Use the standard model for three- or four-reference composition. For mask inpainting or more precise control, evaluate GPT-Image-2.

How should I store the result?

Download url responses promptly into your own object storage. Use b64_json for direct embedding or offline persistence. Do not assume temporary URLs remain available indefinitely.

xAI multi-image editing — upstream multi-image workflow and input ordering
xAI Grok Imagine Image model — standard-model image input
xAI image generation documentation — upstream ratios, resolutions, batching, and response formats
xAI models and pricing — upstream model IDs and list pricing, not LaoZhang API retail pricing
LaoZhang Images API reference — common Images API request and response structure
LaoZhang image generation guide — cross-model selection
LaoZhang model pricing — current group, retail rate, and billing source of truth

Getting Started

Core API

Text APIs

Video Generation APIs

Image Generation APIs

AI Understanding

Grok Imagine 2 API Image Generation and Editing

Create an API key

Read the launch announcement

Choose a model

Current integration scope

Prerequisites

Text-to-image quick start

Python SDK

Reference-image editing

Parameters

Migrating from another Images API

Production acceptance and errors

Frequently asked questions

What are the Grok Imagine 2 model IDs?

Which model should I choose?

Do 1K and 2K cost the same?

Why does this page list only five aspect ratios?

How many reference images can I use?

How should I store the result?

Create an API key

Read the launch announcement

​Choose a model

​Current integration scope

​Prerequisites

​Text-to-image quick start

​Python SDK

​Reference-image editing

​Parameters

​Migrating from another Images API

​Production acceptance and errors

​Frequently asked questions

​What are the Grok Imagine 2 model IDs?

​Which model should I choose?

​Do 1K and 2K cost the same?

​Why does this page list only five aspect ratios?

​How many reference images can I use?

​How should I store the result?

​Sources and related documentation

Choose a model

Current integration scope

Prerequisites

Text-to-image quick start

Python SDK

Reference-image editing

Parameters

Migrating from another Images API

Production acceptance and errors

Frequently asked questions

What are the Grok Imagine 2 model IDs?

Which model should I choose?

Do 1K and 2K cost the same?

Why does this page list only five aspect ratios?

How many reference images can I use?

How should I store the result?

Sources and related documentation