# API изображений: генерация и редактирование

> Создавайте и редактируйте изображения через OpenAI-совместимый Images API в OpenCheese: параметры моделей, примеры на curl и Python, base64, лимиты загрузки.
>
> Веб-страница: https://opencheese.dev/ru/docs/images/ · Все страницы документации: https://opencheese.dev/ru/docs.md

OpenCheese предоставляет OpenAI Images API для всех моделей изображений, включённых для вашего
аккаунта, с тем же API-ключом, что и для текстовых моделей и моделей для кода.

## Найдите модели изображений и их параметры

`GET /v1/images/capabilities` возвращает все модели изображений, доступные вашему ключу, и параметры,
которые принимает каждая из них (например, размер, соотношение сторон, размер изображения, качество,
фон и формат вывода), а также сколько изображений может вернуть один запрос. Запросы проверяются по
этому же списку, поэтому отправляйте только те параметры, которые указаны у модели.

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

Сокращённый ответ:

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

Каждый элемент `params` — это параметр, который можно отправить под его `id`, вместе с допустимыми
значениями. `initial` — разумное начальное значение; `default` действует, если параметр не передан.
`maxImagesPerRequest` — наибольшее допустимое `n`, а `supportsEdit` показывает, принимает ли модель
`/v1/images/edits`.

## Создайте изображение

```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` и `prompt` обязательны. `size`, `quality`, `background`, `output_format`, `aspect_ratio`,
`image_size` и `n` принимаются, если модель их перечисляет.

Каждое изображение приходит в ответе в base64, в `data[].b64_json`; ссылки на размещённые изображения
не выдаются, поэтому `response_format` принимает только `b64_json`. `opencheese_cost_usd` в том же теле
ответа — стоимость запроса для вас в кредитах (USD). Чтобы сохранить первое изображение:

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

Расширение файла выбирайте по формату, запрошенному в `output_format`.

Через 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))
```

## Отредактируйте изображения

`POST /v1/images/edits` принимает `multipart/form-data`: исходное изображение в `image` (или несколько
в `image[]`), а `model` и `prompt` — как поля формы.

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

- Загружать можно PNG, JPEG или WebP: до 5 изображений, до 10 МБ каждое.
- Другие файловые поля, например `mask`, отклоняются.

## Ограничения

- Изображения не возвращаются потоковым ответом: `stream` и `partial_images` отклоняются.
- Некоторые модели возвращают одно изображение на запрос; сколько допускает `n`, показывает
  `/v1/images/capabilities`.
- `moderation` изменить нельзя: действует значение модели по умолчанию.
- Промпт, который не пропускает собственная политика контента модели, отклоняется с
  `moderation_blocked` и не оплачивается. Некоторые модели вместо этого проверяют готовое
  изображение и берут плату за отклонённое: такой ответ — `moderation_blocked_billed`.

## Модели изображений в чат-приложениях

Чат-приложения, которые показывают все модели в одном списке выбора, могут использовать модель
изображений в обычном чате: на `/v1/chat/completions` и `/v1/responses` последнее сообщение
пользователя становится промптом, а изображение приходит в ответе. Формат такого ответа описан на
странице [Chat Completions](https://opencheese.dev/ru/docs/chat-completions.md).

## Цены и расход

Стоимость моделей изображений считается за каждое изображение и зависит от разрешения и качества.
Цены для вашего аккаунта указаны на странице **Цены** в панели после входа, а каждое созданное
изображение отображается на странице **Транзакции** со своей стоимостью.