# Image generation and editing API

> Generate and edit images through OpenCheese's OpenAI-compatible Images API: per-model parameters, curl and Python examples, base64 responses, upload limits.
>
> Web page: https://opencheese.dev/en/docs/images/ · Every docs page: https://opencheese.dev/llms.txt

OpenCheese serves the OpenAI Images API for every image model enabled for your account,
with the same API key as text and code models.

## Find the image models and their parameters

`GET /v1/images/capabilities` lists every image model your key can use and the parameters each
one accepts, such as size, aspect ratio, image size, quality, background and output format,
and how many images one request may return. Requests are checked against the same list, so
send only the parameters a model names.

```bash
curl https://api.opencheese.dev/v1/images/capabilities \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

An abridged answer:

```json
{
  "models": [
    {
      "publicModelId": "IMAGE_MODEL_ID",
      "displayName": "Example Image Model",
      "supportsEdit": true,
      "maxImagesPerRequest": 1,
      "params": [
        { "kind": "enum", "id": "aspect_ratio", "values": ["1:1", "16:9", "9:16"], "initial": "16:9" },
        { "kind": "enum", "id": "quality", "values": ["auto", "low", "medium", "high"], "initial": "auto" }
      ]
    }
  ]
}
```

Each entry in `params` is a parameter you may send under its `id`, with the values it accepts.
`initial` is a sensible starting value; `default` is what applies when you leave the parameter
out. `maxImagesPerRequest` is the largest `n`, and `supportsEdit` says whether the model takes
`/v1/images/edits`.

## Generate an image

```bash
curl https://api.opencheese.dev/v1/images/generations \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "IMAGE_MODEL_ID", "prompt": "A wedge of cheese on a circuit board"}'
```

`model` and `prompt` are required. `size`, `quality`, `background`, `output_format`,
`aspect_ratio`, `image_size` and `n` are accepted where the model lists them.

The response carries each image as base64 in `data[].b64_json`; hosted image URLs are not
issued, so `response_format` accepts only `b64_json`. `opencheese_cost_usd` in the same body is
what the request cost you, in credits (USD). To save the first image:

```bash
curl ... | jq -r '.data[0].b64_json' | base64 --decode > image.png
```

Name the file after the format you asked for in `output_format`.

With the OpenAI Python SDK:

```python
import base64
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
result = client.images.generate(model="IMAGE_MODEL_ID", prompt="A wedge of cheese on a circuit board")
with open("image.png", "wb") as file:
    file.write(base64.b64decode(result.data[0].b64_json))
```

## Edit images

`POST /v1/images/edits` takes `multipart/form-data`: the source image in `image` (or several
in `image[]`), with `model` and `prompt` as form fields.

```bash
curl https://api.opencheese.dev/v1/images/edits \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -F "model=IMAGE_MODEL_ID" \
  -F "prompt=Turn the scene into night" \
  -F "image=@input.png"
```

- Uploads must be PNG, JPEG or WebP: up to 5 images, 10 MB each.
- Other file fields, such as `mask`, are rejected.

## Limits

- Image responses are not streamed: `stream` and `partial_images` are refused.
- Some models return one image per request; `/v1/images/capabilities` says how many `n` allows.
- `moderation` cannot be changed; the model's default applies.
- A prompt the model's own content policy declines is refused with `moderation_blocked` and not
  charged. A few models check the finished picture instead and charge for one they reject:
  that answer is `moderation_blocked_billed`.

## Image models in chat apps

Chat apps that list every model in one picker can use an image model in a normal chat: on
`/v1/chat/completions` and `/v1/responses` the latest user message becomes the prompt and the
picture comes back in the reply. See
[Chat Completions](https://opencheese.dev/en/docs/chat-completions.md) for the reply's shape.

## Pricing and usage

Image models are priced per image, by resolution and quality. The prices for your account are on
the dashboard's **Prices** page after you sign in, and every generated image appears under
**Transactions** with its cost.