API

Images

Generate and edit images: sync, streamed or as async jobs.

Generate an image

POST /v1/images/generations follows the OpenAI Images format, so the OpenAI SDK works unchanged. The image comes back base64-encoded in data[0].b64_json.

curl https://api.greentokens.io/v1/images/generations \
  -H "Authorization: Bearer $GREENTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A lighthouse on a cliff at dusk, watercolor",
    "size": "1024x1024"
  }' | jq -r '.data[0].b64_json' | base64 --decode > lighthouse.jpg

Field	Type	Description
model	string	An image model ID, e.g. `grok-imagine-image-2.0`.
prompt	string	What to draw.
size	string	Output size as `WIDTHxHEIGHT`, e.g. `1024x1024`. Sets the price tier.
n	integer	Number of images. Most models support 1.
stream	boolean	Return the result as a server-sent event instead of JSON.

How images are billed

Each image is billed at a flat price for its size tier, set by the longest side of the output:

1K: up to 1280px
2K: up to 2048px
4K: up to 4096px

Current prices for every model are on the models page. The maximum cost is held from your balance when the request starts and settled at the actual output; a failed or cancelled request releases the hold.

Streaming

With "stream": true the response is text/event-stream. The finished image arrives in an image_generation.completed event.

curl

curl -N https://api.greentokens.io/v1/images/generations \
  -H "Authorization: Bearer $GREENTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-image-2.0", "prompt": "A red bicycle", "stream": true}'

# event: image_generation.completed
# data: {"type": "image_generation.completed", "b64_json": "…", "size": "1024x1024", …}

Edit an image

POST /v1/images/edits takes a multipart form with model, prompt and the source image file. The response has the same shape as a generation.

curl https://api.greentokens.io/v1/images/edits \
  -H "Authorization: Bearer $GREENTOKENS_API_KEY" \
  -F model=grok-imagine-image-2.0 \
  -F prompt="Make it night time, with the lamp lit" \
  -F image=@lighthouse.jpg \
  | jq -r '.data[0].b64_json' | base64 --decode > lighthouse-night.jpg

Async jobs

Send Prefer: respond-async to get a job back immediately instead of holding the connection open. The response is 202, with the job URL in the location header and a suggested poll interval in retry-after.

# 1. Create the job: returns 202 immediately
curl -i https://api.greentokens.io/v1/images/generations \
  -H "Authorization: Bearer $GREENTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -H "Idempotency-Key: poster-2026-09-27-001" \
  -d '{"model": "grok-imagine-image-2.0", "prompt": "A retro travel poster of Lisbon"}'

# HTTP/2 202
# location: /v1/images/jobs/image_…
# retry-after: 2

# 2. Poll until status is "completed"
curl https://api.greentokens.io/v1/images/jobs/image_… -H "Authorization: Bearer $GREENTOKENS_API_KEY"

# 3. Download the image
curl https://api.greentokens.io/v1/images/jobs/image_…/content \
  -H "Authorization: Bearer $GREENTOKENS_API_KEY" -o poster.jpg

Status: queued, in_progress, completed, failed or cancelled.
Cancel: DELETE /v1/images/jobs/{id} while the job is still queued. Once it's in_progress, cancelling returns 409.
Idempotency: an Idempotency-Key (8–160 characters) makes retries safe. The same key and body return the original job; the same key with a different body returns 409.

Async jobs can take longer to start than a direct request. Use them when you can't hold a connection open, not to go faster.