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
| Field | Default | What happens to it |
|---|---|---|
prompt | required | Sent to the model. |
model, tier | tier image | The same resolution as every model route; see Tiers and models. |
n | 1 | How many images. No upper bound is enforced, and every image is billed. |
size | 1024x1024 | Forwarded as sent, not validated. A size the model does not offer comes back as a provider error. |
quality, style, response_format | none | Forwarded 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, metadata | none | Accepted and discarded. |
Quick start
Ask for one image as base64 and write it to disk:
- cURL
- Python
- TypeScript
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'])"
import base64, requests
BASE = "https://<your tenant host>/public/v1"
HEADERS = {"Authorization": "Bearer kapi_..."}
r = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
"prompt": "A line drawing of a lighthouse on a headland at dawn",
"size": "1024x1024", "response_format": "b64_json",
})
r.raise_for_status()
body = r.json()
with open("lighthouse.png", "wb") as f:
f.write(base64.b64decode(body["data"][0]["b64_json"]))
print(body["model"], "on", body["provider"])
import { writeFile } from "node:fs/promises";
const BASE = "https://<your tenant host>/public/v1";
const headers = { Authorization: "Bearer kapi_...", "Content-Type": "application/json" };
const r = await fetch(`${BASE}/images/generations`, {
method: "POST", headers,
body: JSON.stringify({
prompt: "A line drawing of a lighthouse on a headland at dawn",
size: "1024x1024", response_format: "b64_json",
}),
});
if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
const body = await r.json();
await writeFile("lighthouse.png", Buffer.from(body.data[0].b64_json, "base64"));
console.log(body.model, "on", body.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
typeandmessagebut nocode, and an empty tier answers 422 with a top-levelcodeofno_models_for_tier. Match on the status and the message.
Limits and behaviour
nhas no ceiling in the gateway; a large value is limited only by the provider and billed in full.- Nothing about
size,qualityorstyleis 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
imageanswer the default tier; a chat model named inmodelis 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 taggedimage; 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: readmessage; 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].urlis missing: the model answered in base64; readb64_json, or setresponse_formattourlfor a provider that hosts images.
The same task in the platform