# Image generation

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

OpenAI's Images API, generations only, for the OpenAI SDK: a prompt in, images out as `b64_json`, never streamed. It serves the same models and checks the same declarations as `POST /api/v1/images`: `model` and `prompt` suffice, and the model's first declared size is the default. `style` is accepted and never forwarded, the SDK's `standard` and `hd` qualities match no declared quality, and unknown fields are dropped. `GET /api/v1/images/models` lists the image models your key can call.

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`.
- `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.
- `moderation` (string): Forwarded only to a model that takes it.
- `response_format` (string, one of `b64_json`): Every image is answered as `b64_json`; `url` is a 400.
- `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 as `b64_json` (with any `revised_prompt`), the rendering facts the provider echoes (`background`, `output_format`, `quality`, `size`), and `usage` in OpenAI's names, 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/generations \
  -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"
}'
```

## Example response

```json
{
  "created": 1792900000,
  "data": [
    {
      "b64_json": "iVBORw0..."
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 4175,
    "total_tokens": 4175,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "cost": 0.03
  }
}
```