NewMiniMax H3 Lite is live: our cheapest video model, at a launch price until Dec 31. Try it free

OG filename: how-to-use-grok-imagine-api-cover-v3.png
All guides
How-to

How to Use the Grok Imagine API in 2026

Generate Grok Imagine images in about four seconds from your own code with the AiWings API: create a key, send one request, and get a permanent image link. Step by step, in cURL, JavaScript and Python.

·5 min read·

How to Use the Grok Imagine API in 2026

Want Grok Imagine images in your own app, script or automation? This guide shows how to make them with the AiWings API, step by step. Grok Imagine is fast, about four seconds an image, with a strong sense of style, and it handles unusual shapes like phone wallpapers. You use one AiWings key, pay per image from your AiWings credits, and get back a permanent link to every file.

What you need

  • An AiWings account. Sign in with Google; new accounts get 10 free credits, enough for 3 Grok Imagine images.
  • An AiWings API key, which you create in the next step.
  • Somewhere to run code on a server: a script, a backend route, a serverless function or an automation tool that can send HTTP requests. Keys don’t work from browser or mobile app code, where anyone could read them.

Step 1: Create an API key

  1. 1Sign in to AiWings and open the API page in your dashboard.
  2. 2Click Create key, give it a name (for example “my-app production”) and, if you like, a monthly credit limit.
  3. 3Copy the key. It starts with aiw_live_ and is shown only once.
  4. 4Save it as an environment variable on the machine or service that will call the API.
export AIWINGS_API_KEY="aiw_live_your_key_here"

The API uses the same credits as AiWings in ChatGPT, Claude and the dashboard, so there’s no separate plan to buy. Every request sends the key in the Authorization header as a Bearer token.

Create an API key

Step 2: Know your options

AiWings offers Grok Imagine, xAI’s image model. It returns an image in about four seconds:

Modelmodel valueSizeReference imagesCost per image
Grok Imaginegrok-imagine1KUp to 13 credits ($0.03)

Prices are at the top-up rate of $0.01 per credit, and plans include more credits per dollar. Each finished job reports exactly what it cost in its credits field, and GET /v1/models lists every price. Aspect ratios: 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.

Step 3: Make your first image

Send a POST request to /v1/images with a prompt and the model. With "wait": true you get the finished image back in the same call, usually within a few seconds. Each one costs 3 credits ($0.03):

1curl https://aiwings.io/api/v1/images \
2 -H "Authorization: Bearer $AIWINGS_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "prompt": "An oil painting of a spiral galaxy in the style of a baroque ceiling fresco, swirling clouds, gilded edges, dramatic light",
6 "model": "grok-imagine",
7 "aspect_ratio": "4:3",
8 "wait": true
9 }'
10
11# Still "processing"? Ask again with the id:
12curl "https://aiwings.io/api/v1/images/IMAGE_ID?wait=30" \
13 -H "Authorization: Bearer $AIWINGS_API_KEY"
POST /v1/imagesShell

With "wait": true the request holds until the image is ready, for up to 60 seconds, so most images come back in one call with status "succeeded". Higher quality settings can take longer; if the status is still "processing", the loop asks again with GET /v1/images/{id}?wait=30.

output.url is a permanent link to the file. If an image fails, status is "failed", error.message says why, and the credits are refunded automatically. Every image you make through the API also shows up in your AiWings library.

Step 4: Restyle a reference image

Grok Imagine takes one reference image. Pass it in reference_images and describe the new style, or pass the id of an AiWings image as source_generation_id:

1curl https://aiwings.io/api/v1/images \
2 -H "Authorization: Bearer $AIWINGS_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "prompt": "Turn this coffee bag into a 1950s magazine advert, halftone print, bold retro headline, cream background",
6 "model": "grok-imagine",
7 "aspect_ratio": "1:1",
8 "reference_images": [
9 "https://example.com/coffee-bag.png"
10 ],
11 "wait": true
12 }'
13
14# Still "processing"? Ask again with the id:
15curl "https://aiwings.io/api/v1/images/IMAGE_ID?wait=30" \
16 -H "Authorization: Bearer $AIWINGS_API_KEY"
POST /v1/imagesShell

To upload a file from your computer first, use POST /v1/uploads, then pass the url it returns in reference_images. The API docs show the full flow.

Step 5: Use the tall and wide shapes

Grok Imagine supports shapes most models don’t, which saves cropping. Change only aspect_ratio:

"aspect_ratio": "9:20"     a phone wallpaper or story
"aspect_ratio": "20:9"     an ultra-wide banner
"aspect_ratio": "2:1"      a website hero

See what Grok Imagine makes

Real, unedited Grok Imagine images, each made from a single request.

A baroque oil painting still life with a pocket watch, a melting candle and a wine glass containing a tiny spiral galaxy
Oil painting, in secondsGrok Imagine · 1K
A red fox asleep curled inside a hollow tree stump filled with glowing moss and fireflies in a dark forest
Photorealistic fantasyGrok Imagine · 1K
The kraft coffee bag from the reference image redrawn as a 1950s illustrated advertisement poster with warm limited colors
Restyle a reference imageGrok Imagine · 1K
A tall phone wallpaper of a glowing bioluminescent jellyfish drifting through a deep ocean with a constellation-like pattern in its bell
Phone wallpapers at 9:20Grok Imagine · 1K

More models with the same key

Your key isn’t limited to Grok Imagine. The same key, balance and request format cover every video and image model on AiWings. To switch, change the model field: video models go to POST /v1/videos and image models to POST /v1/images.

Modelmodel valueEndpointFrom
Seedance 2.0seedance-2.0/v1/videos50 credits ($0.50) for 5 seconds at 480p
Seedance 2.5seedance-2.5/v1/videos65 credits ($0.65) for 5 seconds at 480p
MiniMax H3minimax-h3/v1/videos50 credits ($0.50) for 5 seconds at 768p
MiniMax H3 Highspeedminimax-h3-highspeed/v1/videos20 credits ($0.20) for 5 seconds at 768p
MiniMax H3 Liteminimax-h3-lite/v1/videos10 credits ($0.10) for 5 seconds at 480p
GPT Image 2.6 Flaregpt-image-2.6-flare/v1/images7 credits ($0.07) per image
GPT Image 2.6 Sunburstgpt-image-2.6-sunburst/v1/images7 credits ($0.07) per image
GPT Image 2.5 Flaregpt-image-2.5-flare/v1/images2 credits ($0.02) per image
GPT Image 2.5 Sunburstgpt-image-2.5-sunburst/v1/images2 credits ($0.02) per image
GPT Image 2gpt-image-2/v1/images2 credits ($0.02) per image
GPT Image 1.5gpt-image-1.5/v1/images2 credits ($0.02) per image
Nano Banananano-banana/v1/images5 credits ($0.05) per image
Nano Banana 2nano-banana-2/v1/images8 credits ($0.08) per image
Nano Banana Pronano-banana-pro/v1/images19 credits ($0.19) per image
Seedream 5 Liteseedream-5-lite/v1/images5 credits ($0.05) per image
Grok Imaginegrok-imagine/v1/images3 credits ($0.03) per image
Flux Fastflux-fast/v1/images1 credit ($0.01) per image

GET /v1/models returns the same list with every price, size and option, so your code can check what’s available instead of hard-coding it.

See every model with samples

Things to know

  • Grok Imagine makes 1K images. For 2K to 4K, the same key covers Nano Banana 2, Nano Banana Pro and Seedream.
  • It’s at its best with a clear style in the prompt: an oil painting, an anime scene, a retro advert, a photo with a named lens.
  • At a few seconds per image, it suits interactive features where a user is waiting for the result.
  • Send an Idempotency-Key header with each new job (the JavaScript and Python examples do). If a request times out and you retry with the same key, you get the same job back instead of paying twice.
  • Each key has its own rate limit, and you can give each key a monthly credit cap so a bug in one app can’t spend your whole balance.
  • Output URLs are public but unguessable, like a share link. Download the file to your own storage if you need to control who can see it.

If something goes wrong

  • 401 authentication_failed: the key is missing, mistyped or revoked. Check the Authorization header reads Bearer followed by your key.
  • 400 invalid_request: a field isn’t allowed for that model, for example a quality or aspect ratio it doesn’t support. The error’s param names the field to fix.
  • 402 insufficient_credits: your balance can’t cover the image. Top up in the dashboard and send the request again.
  • 403 spend_limit_reached: this key hit its monthly credit limit. Raise or remove the limit on the API page.
  • 429 rate_limited or too_many_jobs: you’re sending too fast or have too many jobs rendering at once. Wait for the Retry-After time, or for a image to finish.
  • The image failed with a content error: the prompt or image was blocked by the model’s safety filter. Reword it; the credits were already refunded.

Bottom line

You don’t need a separate xAI account to put Grok Imagine in your product. One AiWings key gives your code Grok Imagine, plus GPT Image, Nano Banana, Seedream, Flux and video models, billed from one balance, with permanent links and automatic refunds on failures. Prefer no code? The same models work in ChatGPT and Claude.

Read the full API reference

FAQ

Is this the official Grok Imagine API?

No. AiWings is an independent service that runs Grok Imagine for you. You use an AiWings key and AiWings credits, with no xAI account or separate billing.

How much does a Grok Imagine image cost through the API?

3 credits ($0.03) per image. Failed images are refunded.

How fast is it?

Usually about four seconds per image, so with "wait": true you get the URL back in the same request.

Can I use it from n8n, Make or Zapier?

Yes, any tool that can send an HTTP request works. Send the POST request from Step 3; the response contains the image URL.