Geração de imagens (API OpenAI Images)

POST /v1/images/generations gera imagens no formato da API OpenAI Images: você envia uma solicitação e recebe a imagem na mesma resposta. Ele é um adaptador sobre a mesma fila que POST /api/media/generate: os modelos, o preço, a verificação de saldo, o failover de fornecedores e a cobrança são compartilhados, portanto a mesma geração custa o mesmo nos dois endereços.

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

Resposta (HTTP 200):

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

Passe a chave como Authorization: Bearer sk-pv-… ou x-api-key. O SDK oficial da OpenAI funciona sem alterações:

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)

Campos desconhecidos e background, style, output_format, output_compression, moderation, stream e partial_images são recusados com 400 pelo nome, em vez de serem descartados silenciosamente — caso contrário, você pagaria por uma imagem que não pediu. Modelos que precisam de uma imagem de origem (edição, aumento de resolução, preenchimento) não funcionam neste endereço, porque não há como passar uma imagem aqui; use POST /api/media/generate.

A solicitação permanece aberta até a conclusão da tarefa, por até 300 segundos. O tempo mediano é de 15 a 85 segundos, dependendo do modelo; gerações individuais nos modelos mais lentos levam de 3 a 4 minutos. Defina o tempo limite do cliente como pelo menos 300 segundos (o padrão do SDK da OpenAI é 600).

• Toda resposta, incluindo erros após a criação da tarefa, contém o cabeçalho x-pv-media-job-id com o id da tarefa.
• Se a tarefa não for concluída em 300 segundos, a resposta será 504 com cause: image_generation_timeout e o id da tarefa na mensagem. A geração continua em execução: obtenha-a em GET /api/media/jobs/{id}.
• Se a conexão cair (tempo limite do app, rede), a tarefa ainda será concluída. GET /v1/images/generations?limit=20 (até 100) lista as imagens recentes desta chave com o status, os links e o valor cobrado cost_rub.

Nada é cobrado no envio. Somente uma geração concluída com sucesso é cobrada, pelo mesmo preço de /api/media-catalog e da cotação de POST /api/media/price. Uma geração malsucedida retorna 502 com a mensagem "Nothing was charged" e não custa nada. O valor cobrado é retornado no cabeçalho x-pv-cost-rub. Se o saldo não puder cobrir a geração, a resposta será 402 antes do início de qualquer tarefa.

Qualquer app que possa gerar imagens por meio de um provedor compatível com OpenAI funciona. Usando o Cherry Studio como exemplo:

1. Adicione um provedor do tipo OpenAI com o endereço da API https://getvibeapi.com (o app adiciona /v1 por conta própria) e sua chave sk-pv-….
2. Adicione o modelo manualmente, usando um id de https://getvibeapi.com/api/media-catalog (somente entradas com kind: "image"), por exemplo, nano-banana ou gpt-image-2. A lista de modelos do app mostra modelos de texto; os modelos de mídia não aparecem nela.
3. Gere a partir do recurso de pintura / geração de imagens do app, não a partir do chat comum. O chat envia a solicitação para /v1/chat/completions, onde os modelos de imagem não funcionam.
4. Se o app permitir definir um tempo limite da solicitação, defina-o como pelo menos 300 segundos. Uma imagem da qual o app desistiu aparece em GET /v1/images/generations. Tentar novamente pelo app cria uma nova geração, que é cobrada separadamente.

O modo que edita uma imagem enviada em aplicativos desse tipo é chamado de /v1/images/edits, que também é disponibilizado (veja abaixo).

POST /v1/images/edits recebe a solicitação do SDK da OpenAI (multipart/form-data: o arquivo em image, ou vários arquivos em image[], com prompt, model, size, quality e response_format) ou JSON com images: [{"image_url": "…"}]. Ele funciona como a geração acima: a mesma resposta, o mesmo tempo de espera, o mesmo x-pv-media-job-id e o mesmo preço que POST /api/media/generate com uma imagem de origem; uma edição malsucedida não é cobrada. O modo de edição do modelo é escolhido no catálogo. Um mask é recusado com 400 unsupported_parameter, e um modelo que não aceita imagem de origem com model_cannot_edit. Para uma edição com máscara, use POST /api/media/generate e consulte GET /api/media/jobs/{id} — veja o guia de geração assíncrona. Vídeos não são gerados de forma síncrona: /v1/video/generations e /v1/videos também respondem com 410 (detalhes).

No catálogo e em códigos novos, use nano-banana-pro. Para migrar clientes assíncronos existentes, o valor gemini-3-pro-image ainda é aceito apenas no campo model da solicitação /api/media/generate e é resolvido para o mesmo modelo público. Ele não é publicado na descoberta nem nos preços.