Skip to main content
POST
Text-to-image: generate an image from a prompt (official channel)
🔒 Requires the GrokOfficial group, granted on application: Grok Imagine Official is not in the Default group; access must be requested before you can call it (including the Playground on this page). Without access, or with a pay-per-request Token, every call returns 503. See Grok Imagine Official Overview - Group Setup.
The interactive Playground on the right lets you test the endpoint directly. Enter your API Key in Authorization (format: Bearer sk-xxx), fill in prompt, pick the model, resolution, and aspect_ratio (plus quality for 2.0), and send.
When to use this page: text-to-image, one image per call. This channel does not offer image editing yet — for reference-based edits or several images per call, use Grok Imagine Reverse.
⚠️ The three most common pitfalls
  1. Use resolution, not size: size is not mapped to a resolution tier, so the image is generated and billed at the default 1k.
  2. Mistakes return errors: out-of-range resolution / aspect_ratio returns 422 and quality: "high" returns 400 — the opposite of the reverse channel’s silent fallback.
  3. Always send n = 1: for several images, send several requests concurrently.
All image APIs are synchronous: there is no async task ID, so if the client disconnects the result is lost but the request is still billed. grok-imagine-image-2.0 at medium and 2K takes about 60–80 seconds, so set the client timeout to 360 seconds. See Image API Notes & Best Practices.

Code Examples

Python (OpenAI SDK)

Python (requests)

cURL

Node.js (fetch)

Parameter Quick Reference

Price per image (same as xAI):
Model pricing is aligned with the official sites and may change when they do; the table above is for reference only, and the Model Pricing tab in the top navigation is authoritative: Model Pricing.

Response Format

  • Each item in data[] has either url or b64_json, depending on response_format.
  • Download returned image links right away; do not keep referencing them.
  • usage is a placeholder (prompt_tokens is always 1000 × image count) and cannot be used for reconciliation — the console billing records are authoritative.
  • created is always 0; do not use it for timing.

Authorizations

Authorization
string
header
required

API Key from the APIYI console (Token group must include GrokOfficial)

Body

application/json
model
enum<string>
default:grok-imagine-image
required

Model ID:

  • grok-imagine-image — standard, $0.02 per image at every resolution
  • grok-imagine-image-quality — high quality, $0.05 / $0.06 / $0.07 at 1k / 1.5k / 2k
  • grok-imagine-image-2.0 — newer model, low $0.04 / $0.05 / $0.06, medium $0.06 / $0.07 / $0.08
Available options:
grok-imagine-image,
grok-imagine-image-quality,
grok-imagine-image-2.0
prompt
string
required

Prompt in any language. Describe the subject, scene, style, and lighting in detail

Example:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
enum<integer>
default:1

Image count. Fixed at 1 on this channel; call concurrently for more images

Available options:
1
resolution
enum<string>
default:1k

Resolution tier (lowercase), which also sets the price: 1k (default) / 1.5k / 2k.

Out-of-range values (such as 4k or 1K) return 422. Do not use size instead — it is not mapped to a resolution tier.

Available options:
1k,
1.5k,
2k
aspect_ratio
enum<string>
default:1:1

Output aspect ratio, default 1:1. Measured examples: grok-imagine-image at 1k + 3:2 outputs 1248×832; -quality at 2k + 9:16 outputs 1584×2816.

Out-of-range values (such as 5:7) return 422.

Available options:
1:1,
16:9,
9:16,
4:3,
3:4,
3:2,
2:3
quality
enum<string>

Quality tier, only for grok-imagine-image-2.0: low (default) or medium ($0.02 more per image, slower).

high returns 400. The other two models take no quality.

Available options:
low,
medium
response_format
enum<string>
default:url

Response format: url (default; download and store the image right away) or b64_json (plain base64, no data: prefix)

Available options:
url,
b64_json

Response

Image generated successfully

created
integer

Always 0; do not use it for timing

Example:

0

data
object[]

Image results (one item on this channel)

usage
object

Placeholder — do not reconcile with it. prompt_tokens is always 1000 × image count; the console billing records are authoritative