> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# BeatAPI Image API

> Сравните модели генерации изображений BeatAPI, ограничения референсов, разрешения, соотношения сторон и контракты запросов.

# Image API

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

| Модель                                                        | Входные данные               | Обязательные поля | Основные настройки                                                                  |
| ------------------------------------------------------------- | ---------------------------- | ----------------- | ----------------------------------------------------------------------------------- |
| [`qwen-image-2.1`](/image-api/qwen-image-2-1)                 | Текст, изображения-референсы | `model`, `prompt` | До 10 референсов, 1K/2K, прозрачный PNG/WebP, улучшение промпта по условиям запроса |
| [`nano-banana`](/image-api/nano-banana)                       | Текст, изображения-референсы | `model`, `prompt` | До 3 референсов, фиксированное 1K, PNG/JPEG                                         |
| [`nano-banana-2`](/image-api/nano-banana-2)                   | Текст, изображения-референсы | `model`, `prompt` | До 14 референсов, 1K/2K/4K, PNG/JPEG                                                |
| [`nano-banana-2.1`](/image-api/nano-banana-2-1)               | Текст, изображения-референсы | `model`, `prompt` | Те же поля и цены, что у Nano Banana 2. До 14 референсов, 1K/2K/4K, PNG/JPEG        |
| [`nano-banana-2-lite`](/image-api/nano-banana-2-lite)         | Текст, изображения-референсы | `model`, `prompt` | До 14 референсов, фиксированное 1K, PNG/JPEG                                        |
| [`nano-banana-pro`](/image-api/nano-banana-pro)               | Текст, изображения-референсы | `model`, `prompt` | До 14 референсов, 1K/2K/4K, PNG/JPG                                                 |
| [`gpt-image-2`](/image-api/gpt-image-2)                       | Текст, изображения-референсы | `model`, `prompt` | До 16 референсов, широкий выбор соотношений сторон, до 4K                           |
| [`gpt-image-2.5-flare`](/image-api/gpt-image-2-5-flare)       | Текст, изображения-референсы | `model`, `prompt` | До 16 референсов, 16 соотношений сторон, до 4K                                      |
| [`gpt-image-2.5-sunburst`](/image-api/gpt-image-2-5-sunburst) | Текст, изображения-референсы | `model`, `prompt` | До 16 референсов, 16 соотношений сторон, до 4K                                      |
| [`seedream-5-pro`](/image-api/seedream-5-pro)                 | Текст, изображения-референсы | `model`, `prompt` | До 10 референсов, 1K/2K                                                             |
| [`grok-imagine-image-2.0`](/image-api/grok-imagine-image-2-0) | Текст, изображения-референсы | `model`, `prompt` | До 5 референсов, автоматический выбор режима редактирования                         |

На странице выбранной модели описаны все поля, значения по умолчанию, допустимые значения, правила сочетания параметров, примеры запросов, ответы и ошибки.

## Список доступных моделей

`GET /v1/media/models`

| Параметр     | Где передаётся | Тип    | Обязателен | Допустимые значения |
| ------------ | -------------- | ------ | ---------- | ------------------- |
| `media_type` | Строка запроса | string | Нет        | `image`, `video`    |

Этот общедоступный метод не требует авторизации.

```bash
curl "https://api.beatapi.io/v1/media/models?media_type=image"
```

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "gpt-image-2",
        "object": "generation_model",
        "name": "GPT Image 2",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-flare",
        "object": "generation_model",
        "name": "GPT Image 2.5 Flare",
        "media_type": "image",
        "input_modes": ["text", "image"]
      },
      {
        "id": "gpt-image-2.5-sunburst",
        "object": "generation_model",
        "name": "GPT Image 2.5 Sunburst",
        "media_type": "image",
        "input_modes": ["text", "image"]
      }
    ]
  }
}
```

| Поле          | Тип       | Значение                                        |
| ------------- | --------- | ----------------------------------------------- |
| `id`          | string    | Постоянный публичный ID модели                  |
| `object`      | string    | `generation_model`                              |
| `name`        | string    | Отображаемое название                           |
| `media_type`  | string    | `image` или `video`                             |
| `input_modes` | string\[] | Любые из `text`, `image`, `frames`, `reference` |

Внутренняя маршрутизация к поставщикам не входит в публичный контракт.

## Общие правила создания задачи

`POST /v1/images/tasks`

| Заголовок         | Тип    | Обязателен         | Правила                                                         |
| ----------------- | ------ | ------------------ | --------------------------------------------------------------- |
| `Authorization`   | string | Да                 | `Bearer <BEATAPI_API_KEY>`                                      |
| `Content-Type`    | string | Да                 | `application/json`                                              |
| `Idempotency-Key` | string | Нет, рекомендуется | До 255 символов; один ключ на одну логическую операцию создания |

Тело запроса должно соответствовать ровно одной схеме модели. Поле `model` определяет схему; неизвестные поля отклоняются.

```bash
curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: image-gpt-image-2-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial product photograph on a warm stone pedestal.",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'
```

Корректный запрос возвращает `201 Created` с `data.id`, `task_kind="image"`, выбранной `model`, `status="queued"`, данными об использовании и `request_id`. Проверяйте `GET /v1/tasks/{task_id}` каждые 5–10 секунд до `succeeded` или `failed`. Готовое изображение доступно в `data.output.media[]` и `data.output.r2_url`.

Точный повтор с тем же ключом идемпотентности возвращает уже принятую задачу. Тот же ключ с другим телом запроса даёт `409 idempotency_conflict`.

## Общие ошибки

| HTTP  | Типичный код                                                                                     | Что делать                                                                                    |
| ----- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `400` | `bad_request`                                                                                    | Исправьте поля, значения, сочетания параметров, количество файлов или URL медиа               |
| `400` | `content_policy_violation`                                                                       | Измените промпт или входные данные; не отправляйте повтор без изменений                       |
| `401` | `missing_api_key` / `invalid_api_key`                                                            | Передайте Bearer-ключ либо замените неверный, просроченный, отключённый или исчерпавший лимит |
| `402` | `insufficient_credits`                                                                           | Пополните баланс перед созданием новой задачи                                                 |
| `403` | `forbidden`                                                                                      | Ключу или аккаунту запрещена операция, например модель недоступна за счёт бонуса              |
| `409` | `idempotency_conflict`                                                                           | Повторно используйте ключ только с тем же телом запроса                                       |
| `429` | `rate_limit_exceeded`                                                                            | Подождите время из `Retry-After`                                                              |
| `500` | `internal_error`                                                                                 | Повторите один раз после задержки                                                             |
| `503` | `processing_unavailable` / `processing_timeout` / `processing_failed` / `result_transfer_failed` | Повторите позже с увеличивающейся задержкой; средства не списаны                              |

Ответ с ошибкой содержит `error.code`, английское `error.message`, `error.retryable`, `error.request_id`, а при `429` — `error.retry_after_seconds`. Если уже принятая задача завершилась ошибкой, запрос статуса всё равно возвращает `200`: проверьте `data.error_code`. Все коды и правила повторов описаны в разделе [ошибок](/errors). Страницы отдельных моделей ниже содержат полные контракты для рабочей среды.