# Images

`POST https://api.llm.buzz/api/v1/images`

OpenRouter's Image API: a text prompt in, images out, never streamed. The request resolves to one size the model declares: an explicit `size`; else `resolution` keeps the sizes of that tier and `aspect_ratio` picks the first of them with that ratio; with neither, the model's first size. Only the parameters the model declares reach the provider. A provider may return fewer images than `n`, and you pay for the images returned: a model priced per image bills each image, one priced per token the tokens the provider reports. A high-quality image can take minutes, so allow a long client timeout. `GET /api/v1/images/models` lists the image models your key can call and the values each takes.

Authentication: an inference key, as `Authorization: Bearer KEY`.

## Body

- `model` (string, required): An image model from `GET /api/v1/images/models`, such as `qwen/qwen-image-3`; a chat or embeddings model is a 400 on `model`. The `:floor` and `:nitro` suffixes work as on chat.
- `prompt` (string, required): What to draw, 1 to 32,000 characters.
- `n` (integer): How many images, 1 to 10 and at most the model's most images per request.
- `size` (string): A size the model declares, `WIDTHxHEIGHT` or `auto`, or a resolution tier such as `1K` or `2K`, read as `resolution`.
- `aspect_ratio` (string): A ratio the model declares, such as `16:9`: the first declared size with that ratio.
- `resolution` (string): A tier the model declares, such as `1K` or `2K`.
- `quality` (string): A value the model declares; a model that declares none ignores the field.
- `background` (string): A value the model declares; a model that declares none ignores the field.
- `output_format` (string, one of `png`, `jpeg`, `webp`): A format the model declares; a model that declares none ignores the field.
- `output_compression` (integer): 0 to 100, forwarded only to a model that takes it.
- `seed` (integer): Forwarded only to a model that takes it.
- `provider` (object): Steers one request across the model's providers. With the OpenAI SDK, send it in `extra_body`. Every field accepts `null`. A name matches a provider's display name, its tag or the tag's first part, ignoring case: `llm.buzz` or `llm-buzz` names llm.buzz's own provider, and `llm-buzz/eu` only its capacity in the EU.
  - `order` (string[]): Try these providers first, in this order, then the others. At most 64 names.
  - `only` (string[]): Use only these providers.
  - `ignore` (string[]): Never use these providers.
  - `allow_fallbacks` (boolean): `false` stops moving to other providers.
  - `sort` (string, one of `price`, `throughput`, `latency`, `smart`): The order to try providers in. Ignored when `order` is set.
  - `zdr` (boolean): `true` keeps the request on providers that declare 0 days of retention.
  - `data_collection` (string, one of `allow`, `deny`): `deny` keeps the request on providers that declare no training and 0 days of retention.
- `user` (string): Your end user's label, recorded and never forwarded.

## Responses

- 200: The images, each as `b64_json` with the `media_type` its bytes show (PNG, JPEG or WebP), and `usage`, whose `cost` is in US dollars. The `X-Generation-Id` header names the call's generation record, `GET /api/v1/generation`.
- 400: Before any provider call: a field is missing or malformed, or names a size, ratio, tier or value the model does not declare, or `n` is above its most images. `metadata.param` names the field, and the message what to send. A chat or embeddings model, `input_references`, `stream: true`, `output_format: "svg"` and `response_format: "url"` are refused the same way.
- 401: No key, or the key is unknown, expired, revoked or disabled.
- 402: Your balance is spent and the model is not free, or the request could cost more than your balance.
- 404: No model has this name, or your key may not call it.
- 429: Providers are throttling, or the model is at capacity (`unavailable_route`): retry after `Retry-After` seconds. Or a free offer's allowance is used (`free_allowance_exceeded`): your organization's tokens, or your key's requests per minute. Choose a paid model, or for the per-minute limit retry after `Retry-After` seconds.

## Example (curl)

```bash
curl -X POST https://api.llm.buzz/api/v1/images \
  -H "Authorization: Bearer $LLM_BUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen/qwen-image-3",
  "prompt": "A honeycomb engraved on a copper plate",
  "aspect_ratio": "16:9"
}'
```

## Example response

```json
{
  "created": 1792900000,
  "data": [
    {
      "b64_json": "iVBORw0...",
      "media_type": "image/png"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4175,
    "total_tokens": 4175,
    "cost": 0.03
  }
}
```