Images

Generate an image, save the returned bytes, and inspect request status.

Before You Begin

Complete the quickstart to configure the Router origin and API key. Image generation requires an enabled image model, images.write access, and available workspace credits. Use the model catalog to find a model, then confirm that its endpoint uses the image-generation protocol.

This guide covers /v1/images/generations. Models that use the separate inference protocol belong to Native Inference; their controls and response format differ.

Generate an Image

The current image-generation profile produces one square image. Replace the model in this example with an enabled model supported by the endpoint. Generate a new Idempotency-Key for each new logical request and retain it with your request record.

curl --fail --show-error --request POST \
  --url "$AUDIOLAB_API_URL/v1/images/generations" \
  --header "Authorization: Bearer $AUDIOLAB_API_KEY" \
  --header 'Idempotency-Key: YOUR_UNIQUE_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "xai/grok-imagine-image",
  "prompt": "VALUE"
}'

Use the image-generation reference for supported models and exact prompt and output controls. Editing, input images, and arbitrary provider options are outside this profile.

Save the Result

A successful response contains one entry in data, with b64_json and mime_type. Decode the base64 into bytes and save or serve it using the returned MIME type. The response is JSON containing image data; it is not a raw image download.

Store the output when you receive it. Output bytes are returned once and are not retained for replay. Record the x-request-id response header alongside the saved asset.

Handle an Uncertain Result

Use Get Image Status with the originating API key and requests.read to inspect a request whose outcome is uncertain. The status operation returns metadata, not the generated image.

Reusing the idempotency key does not generate a replacement image or replay its bytes. A request still awaiting reconciliation can retain its credit hold. Follow Errors and Debugging before submitting a new generation.