Skip to main content

Generate images

POST /public/v1/images/generations takes an OpenAI-shaped request, routes it to an image model by the image tier or by model id, and returns the image as base64 or as a URL the provider hosts. It shares the key and the base URL with every other model route, so one integration can chat, embed and draw.

Who can use it: anyone holding an API key with the Chat or the Completions scope. An administrator must have tagged at least one model with the image tier; GET /public/v1/models?kind=image shows them.

The fields​

FieldDefaultWhat happens to it
promptrequiredSent to the model.
model, tiertier imageThe same resolution as every model route; see Tiers and models.
n1How many images. No upper bound is enforced, and every image is billed.
size1024x1024Forwarded as sent, not validated. A size the model does not offer comes back as a provider error.
quality, style, response_formatnoneForwarded only when you set them, not validated. The values are the provider's: standard or hd and low, medium, high or auto for quality depending on the model; vivid or natural for style; url or b64_json for the format. A self-hosted model answers in b64_json unless told otherwise.
user, metadatanoneAccepted and discarded.

Quick start​

Ask for one image as base64 and write it to disk:

curl -X POST "https://<your tenant host>/public/v1/images/generations" \
-H "Authorization: Bearer kapi_..." \
-H "Content-Type: application/json" \
-d '{"prompt": "A line drawing of a lighthouse on a headland at dawn", "size": "1024x1024", "response_format": "b64_json"}' \
| python -c "import json,sys,base64; d=json.load(sys.stdin); open('lighthouse.png','wb').write(base64.b64decode(d['data'][0]['b64_json'])); print(d['model'], d['provider'])"

What comes back​

The body is created, data (one entry per image with b64_json or url, and revised_prompt when the provider rewrote yours), model and provider. The gateway also sets X-Model, X-Provider and X-Latency-Ms headers, which the public edge does not relay on the current build, so the generation time is not available through the public API. A url is the provider's and expires on the provider's schedule, so download it rather than storing the link.

What it costs and what is checked​

  • Spend is recorded at a flat rate per image, four cents at the time of writing, against the tenant's, the key owner's and the team's budget counters. Tokens are not involved.
  • The route runs the key's rate limit, the AI Gateway's rate limit and the budget check. It runs no token quota check and has no circuit breaker; a failing provider is retried on the next call as if nothing had happened.
  • Its refusals differ in shape from the chat routes: a rate-limit or budget 429 on this route carries type and message but no code, and an empty tier answers 422 with a top-level code of no_models_for_tier. Match on the status and the message.

Limits and behaviour​

  • n has no ceiling in the gateway; a large value is limited only by the provider and billed in full.
  • Nothing about size, quality or style is checked before the call, so a typo reaches the provider and comes back as a 502 provider error rather than a 422.
  • Only models an administrator tagged image answer the default tier; a chat model named in model is refused as not image-capable by the provider, not by the gateway.
  • The image itself is not run through guardrails; the prompt text is subject to the provider's own policy.

Troubleshooting​

  • 422 with no_models_for_tier: no model is tagged image; an administrator adds one on the AI Gateway's Models page.
  • 403 with FORBIDDEN: the key has neither the Chat nor the Completions scope.
  • 429 without a code: read message; it names either the rate limit or the budget rule.
  • 502 naming the size or quality: the provider rejected a value; use one the served model offers.
  • data[0].url is missing: the model answered in base64; read b64_json, or set response_format to url for a provider that hosts images.

The same task in the platform

Describes the platform as of .

Was this page helpful?