Генерация изображений (OpenAI Images API)

Синхронная генерация изображений в формате OpenAI Images API: параметры, ожидание до 300 секунд, оплата только за готовую картинку, настройка Cherry Studio. Редактирование — через асинхронный /api/media/generate.

POST /v1/images/generations — генерация изображений в формате OpenAI Images API: отправили запрос — получили картинку в том же ответе. Это переходник к той же очереди, что и POST /api/media/generate: модели, цена, проверка баланса, переключение поставщиков и списание общие, поэтому одна и та же генерация стоит одинаково по обоим адресам.

POSThttps://plusvibeapi.ru/v1/images/generations

curl https://plusvibeapi.ru/v1/images/generations \
  -H "Authorization: Bearer $PLUSVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"красный велосипед на мосту","n":1,"size":"1024x1024"}'

Ответ (HTTP 200):

{
  "created": 1792706400,
  "data": [{ "url": "https://plusvibeapi.ru/media/r/…/0.png" }]
}

Ключ передаётся как Authorization: Bearer sk-pv-… или x-api-key. Подходит официальный OpenAI SDK:

from openai import OpenAI

client = OpenAI(base_url="https://plusvibeapi.ru/v1", api_key="sk-pv-...", timeout=600)
image = client.images.generate(model="nano-banana", prompt="красный велосипед на мосту", size="1024x1024")
print(image.data[0].url)

Параметры тела

Параметр	Тип	Описание
`model`обяз.	string	Id модели изображений из /api/media-catalog (kind: "image"), например nano-banana, gpt-image-2, flux-2. Принимается и id с префиксом производителя (google/nano-banana), и закреплённый вариант (gpt-image-2:network). Видео- и аудиомодели здесь отклоняются с 400.
`prompt`обяз.	string	Описание изображения.
`n`	number	Только 1: каждая генерация — отдельная задача со своей ценой. Нужно несколько картинок — отправьте несколько запросов.
`size`	string	Размер как пропорция: 1024x1024 → 1:1, 1792x1024 → 16:9, 1024x1792 → 9:16, 1536x1024 → 3:2, 1024x1536 → 2:3; другие значения сокращаются точно (1920x1080 → 16:9). Пропорция, которой у модели нет, отклоняется с перечнем допустимых размеров — замены «на ближайшую» нет. "auto" или отсутствие поля — по умолчанию модели.
`quality`	string	Только для моделей с параметром quality в каталоге; неподдерживаемое значение отклоняется. "auto" — не передавать.
`response_format`	"url" \| "b64_json"	По умолчанию url. b64_json возвращает файл в теле ответа (до 20 МБ).
`user`	string	Принимается и игнорируется.

Неизвестные поля, а также background, style, output_format, output_compression, moderation, stream и partial_images отклоняются с 400 по имени, а не молча отбрасываются: иначе вы заплатили бы за картинку, о которой не просили. Модели, которым нужно исходное изображение (редактирование, апскейл, дорисовка), через этот адрес не работают — передать картинку здесь нельзя; используйте POST /api/media/generate.

Ожидание и таймаут

Запрос держится открытым, пока задача не завершится, — до 300 секунд. Медианное время — от 15 до 85 секунд в зависимости от модели; у самых медленных отдельные генерации идут 3–4 минуты. Поставьте таймаут клиента не меньше 300 секунд (у OpenAI SDK по умолчанию 600).

Каждый ответ, включая ошибки после создания задачи, несёт заголовок x-pv-media-job-id — id задачи.
Если задача не успела за 300 секунд, ответ — 504 с cause: image_generation_timeout и id задачи в тексте. Генерация продолжается: заберите результат через GET /api/media/jobs/{id}.
Если соединение оборвалось (таймаут приложения, сеть), задача всё равно доводится до конца. GET /v1/images/generations?limit=20 (до 100) возвращает последние изображения этого ключа со статусом, ссылками и списанной суммой cost_rub.

Оплата

При отправке ничего не списывается. Списание происходит только за успешно завершённую генерацию — по той же цене, что в /api/media-catalog и в предварительной оценке POST /api/media/price. Неудачная генерация возвращает 502 с текстом «Списания не было» и не стоит ничего. Сумма списания приходит в заголовке x-pv-cost-rub. Если баланса не хватает на генерацию, ответ — 402 до запуска задачи.

Ссылки из data[].url ведут на наш домен и живут 5 дней после завершения генерации, затем отвечают 410 media_result_expired. Сохраняйте файлы у себя.

Ошибки

Параметр	Тип	Описание
`400`	invalid_request_error	Неверное тело: unknown_parameter, unsupported_parameter, unsupported_n, unsupported_size, unsupported_quality, unsupported_model_kind. Исправьте запрос.
`401 / 403`	authentication_error / permission_error	Неверный ключ или IP не в белом списке ключа.
`402`	insufficient_quota	Не хватает баланса на эту генерацию. Задача не создана.
`404`	not_found_error	model_not_found — такой модели изображений нет. Список: /api/media-catalog.
`429`	rate_limit_error	Лимит медиа-запросов; повторяйте после Retry-After.
`502`	upstream_error	Генерация не удалась. Списания не было, можно повторить.
`503`	upstream_error	Модель сейчас недоступна у всех поставщиков. Задача не создана, повторите позже или выберите другую модель.
`504`	upstream_error	image_generation_timeout — задача ещё идёт; заберите её по id из x-pv-media-job-id.

Десктопные приложения (Cherry Studio и другие)

Подойдёт любое приложение, которое умеет генерировать картинки через OpenAI-совместимый провайдер. На примере Cherry Studio:

Добавьте провайдера с типом OpenAI, адрес API — https://plusvibeapi.ru (приложение само дописывает /v1), ключ — sk-pv-….
Добавьте модель вручную по id из https://plusvibeapi.ru/api/media-catalog (только записи с kind: "image"), например nano-banana или gpt-image-2. Обычный список моделей приложения показывает текстовые модели, медиа в нём нет.
Генерируйте в разделе рисования / генерации изображений, а не в обычном чате. Чат отправляет запрос на /v1/chat/completions, а модели изображений там не работают.
Если в настройках можно задать таймаут запроса, поставьте не меньше 300 секунд. Картинку, которую приложение не дождалось, найдёте в GET /v1/images/generations. Повтор запроса из приложения создаёт новую генерацию, которая оплачивается отдельно.

Режим редактирования загруженной картинки в таких приложениях обращается к /v1/images/edits — этот адрес тоже работает (см. ниже).

Редактирование: /v1/images/edits

POST /v1/images/edits принимает запрос OpenAI SDK (multipart/form-data: файл в image или несколько в image[], поля prompt, model, size, quality, response_format) или JSON с images: [{"image_url": "…"}]. Работает так же, как генерация выше: тот же ответ, то же ожидание, тот же x-pv-media-job-id, та же цена, что у POST /api/media/generate с исходным изображением; неудачная правка не списывается. Режим правки модели выбирается по каталогу сам. Параметр mask отклоняется с ошибкой 400 unsupported_parameter, модель без приёма исходного изображения — с model_cannot_edit. Для правки по маске используйте POST /api/media/generate и опрос GET /api/media/jobs/{id} — руководство по асинхронной генерации. Видео синхронно не генерируется: /v1/video/generations и /v1/videos тоже отвечают 410 (подробнее).

Идентификатор Nano Banana Pro

В каталоге и новом коде используйте nano-banana-pro. Для миграции существующих асинхронных клиентов значение gemini-3-pro-image пока принимается только в поле model запроса /api/media/generate и разрешается в ту же публичную модель. Оно не публикуется в discovery или pricing.

← ПредыдущийVision (изображения в чате)Следующий →Миграция генерации видео