Generación de imágenes (OpenAI Images API)

POST /v1/images/generations genera imágenes en el formato de OpenAI Images API: envías una solicitud y recibes la imagen en la misma respuesta. Es un adaptador sobre la misma cola que POST /api/media/generate: los modelos, el precio, la comprobación del saldo, la conmutación por error del proveedor y el cargo son compartidos, por lo que la misma generación cuesta lo mismo en ambas direcciones.

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"}'

Respuesta (HTTP 200):

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

Pasa la clave como Authorization: Bearer sk-pv-… o x-api-key. El SDK oficial de OpenAI funciona tal cual:

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)

Los campos desconocidos, así como background, style, output_format, output_compression, moderation, stream y partial_images, se rechazan con 400 por nombre en lugar de descartarse silenciosamente; de lo contrario, pagarías por una imagen que no solicitaste. Los modelos que necesitan una imagen de origen (edición, ampliación, relleno) no funcionan en esta dirección, porque aquí no hay forma de pasar una imagen; usa POST /api/media/generate.

La solicitud permanece abierta hasta que termina el trabajo, durante un máximo de 300 segundos. El tiempo mediano es de 15 a 85 segundos, según el modelo; las generaciones individuales en los modelos más lentos tardan entre 3 y 4 minutos. Configura el tiempo de espera de tu cliente en al menos 300 segundos (el valor predeterminado del SDK de OpenAI es 600).

• Cada respuesta, incluidos los errores posteriores a la creación del trabajo, lleva el encabezado x-pv-media-job-id con el id del trabajo.
• Si el trabajo no terminó en 300 segundos, la respuesta es 504 con cause: image_generation_timeout y el id del trabajo en el mensaje. La generación continúa ejecutándose: obtén el resultado desde GET /api/media/jobs/{id}.
• Si la conexión se interrumpe (tiempo de espera de la aplicación o de la red), el trabajo se completa de todos modos. GET /v1/images/generations?limit=20 (hasta 100) muestra las imágenes recientes de esta clave con su estado, enlaces y el importe cobrado cost_rub.

No se cobra nada al enviar la solicitud. Solo se cobra una generación completada correctamente, al mismo precio que en /api/media-catalog y en la cotización de POST /api/media/price. Una generación fallida devuelve 502 con el mensaje "Nothing was charged" y no cuesta nada. El importe cobrado se devuelve en el encabezado x-pv-cost-rub. Si el saldo no puede cubrir la generación, la respuesta es 402 antes de que se inicie cualquier trabajo.

Funciona cualquier aplicación que pueda generar imágenes mediante un proveedor compatible con OpenAI. Usaremos Cherry Studio como ejemplo:

1. Agrega un proveedor de tipo OpenAI con la dirección de API https://getvibeapi.com (la aplicación agrega /v1 por sí misma) y tu clave sk-pv-….
2. Agrega el modelo manualmente usando un id de https://getvibeapi.com/api/media-catalog (solo las entradas con kind: "image"), por ejemplo, nano-banana o gpt-image-2. La lista de modelos de la aplicación muestra modelos de texto; los modelos multimedia no aparecen en ella.
3. Genera desde la función de pintura o generación de imágenes de la aplicación, no desde el chat normal. El chat envía la solicitud a /v1/chat/completions, donde los modelos de imágenes no funcionan.
4. Si la aplicación te permite establecer un tiempo de espera de la solicitud, configúralo en al menos 300 segundos. Una imagen a la que la aplicación dejó de esperar aparece en GET /v1/images/generations. Reintentar desde la aplicación crea una nueva generación que se cobra por separado.

El modo que edita una imagen subida en aplicaciones de este tipo se llama /v1/images/edits, y también está disponible (consulta más abajo).

POST /v1/images/edits procesa la solicitud del SDK de OpenAI (multipart/form-data: el archivo en image, o varios en image[], con prompt, model, size, quality y response_format) o JSON con images: [{"image_url": "…"}]. Funciona igual que la generación anterior: la misma respuesta, la misma espera, el mismo x-pv-media-job-id y el mismo precio que POST /api/media/generate con una imagen de origen; una edición fallida no se cobra. El modo de edición del modelo se elige del catálogo. Un mask se rechaza con 400 unsupported_parameter, y un modelo que no acepta una imagen de origen con model_cannot_edit. Para una edición con máscara, usa POST /api/media/generate y consulta GET /api/media/jobs/{id} periódicamente; consulta la guía de generación asíncrona. El video no se genera de forma síncrona: /v1/video/generations y /v1/videos también responden con 410 (detalles).

En el catálogo y en el código nuevo, usa nano-banana-pro. Para migrar clientes asíncronos existentes, el valor gemini-3-pro-image todavía se acepta únicamente en el campo model de la solicitud /api/media/generate y corresponde al mismo modelo público. No se publica en la información de modelos disponibles ni en los precios.