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

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

curl https://getvibeapi.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"a red bicycle on a bridge","n":1,"size":"1024x1024"}'

Ответ (HTTP 200):

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

Передайте ключ как Authorization: Bearer sk-pv-… или x-api-key. Официальный OpenAI SDK работает без изменений:

from openai import OpenAI

client = OpenAI(base_url="https://getvibeapi.com/v1", api_key="sk-pv-...", timeout=600)
image = client.images.generate(model="nano-banana", prompt="a red bicycle on a bridge", size="1024x1024")
print(image.data[0].url)

Неизвестные поля, а также 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 с идентификатором задачи.
• Если задача не завершилась в течение 300 секунд, ответом будет 504 с cause: image_generation_timeout и идентификатором задачи в сообщении. Генерация продолжается: получите результат из GET /api/media/jobs/{id}.
• Если соединение разрывается (тайм-аут приложения, сеть), выполнение задачи всё равно продолжается до завершения. GET /v1/images/generations?limit=20 (до 100) перечисляет недавние изображения этого ключа с их статусами, ссылками и списанной суммой cost_rub.

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

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

1. Добавьте провайдера типа OpenAI с адресом API https://getvibeapi.com (приложение само добавляет /v1) и вашим ключом sk-pv-….
2. Добавьте модель вручную, используя идентификатор из https://getvibeapi.com/api/media-catalog (только записи с kind: "image"), например nano-banana или gpt-image-2. В списке моделей приложения отображаются текстовые модели; медиамоделей в нём нет.
3. Запускайте генерацию из функции рисования / генерации изображений приложения, а не из обычного чата. Чат отправляет запрос в /v1/chat/completions, где медиамодели не работают.
4. Если приложение позволяет задать тайм-аут запроса, установите его не менее 300 секунд. Изображение, от генерации которого приложение отказалось из-за тайм-аута, будет указано в GET /v1/images/generations. Повторная попытка из приложения создаёт новую генерацию, которая оплачивается отдельно.

Режим, который редактирует загруженное изображение в таких приложениях, называется /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. Для миграции существующих асинхронных клиентов значение gemini-3-pro-image по-прежнему принимается только в поле model запроса /api/media/generate и разрешается в ту же публичную модель. Оно не публикуется в discovery или ценах.