# Generate images

Generate an image through the AI Gateway's image route, with the fields it forwards, the response shape, the flat cost it records, and the checks it does and does not run.

`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](/developers/guides/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**

```bash
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'])"
```

**Python**

```python

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"])
```

**TypeScript**

```typescript

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 `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.

## Related

- [Tiers and models](/developers/guides/tiers-and-models)
- [How limits combine](/developers/guides/how-limits-combine)
- Embeddings, rerank and images

Source: https://docs.katonic.ai/developers/guides/generate-images
