dall-e-3, o gpt-image-1 com capacidade aprimorada de renderização de texto, a mais recente geração gpt-image-2, bem como a série de modelos nano-banana / nano-banana-2 / nano-banana-pro acessados pela mesma interface. Todos eles podem gerar imagens de alta qualidade a partir de descrições textuais.
Este documento apresenta principalmente o fluxo de uso da API OpenAI Images Generations, que permite utilizar facilmente as funcionalidades de geração de imagens da série OpenAI.
Processo de Solicitação
Para usar o OpenAI Images Generations API, primeiro acesse a página OpenAI Images Generations API e clique no botão “Acquire” para obter as credenciais necessárias para as requisições:
Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login para se registrar e entrar. Após o login, você será redirecionado automaticamente para esta página.
Na primeira solicitação, um crédito gratuito será concedido para uso da API.
Modelo GPT-Image-2
gpt-image-2 é o novo modelo de geração de imagens lançado pela OpenAI, que apresenta melhorias significativas em relação ao dall-e-3 e gpt-image-1 nos seguintes aspectos:
- Maior capacidade de seguir instruções: pode compreender com precisão instruções estruturadas complexas, como composição, contagem e relações de posição.
- Renderização de texto mais clara: em cenários como pôsteres, menus, infográficos e logotipos, textos em inglês e números quase não apresentam erros.
- Expressão de estilo mais rica: suporta nativamente vários estilos, como retratos cinematográficos, pôsteres vintage, ilustrações infantis, fotografia de produtos e infográficos.
- Suporte nativo a múltiplas proporções + alta resolução: cobre 5 proporções (1:1, 4:3, 3:4, 16:9, 9:16) em 3 níveis de resolução (1K / 2K / 4K).
model como gpt-image-2. O campo url no resultado é um link permanente hospedado em platform.cdn.xhuoapi.ai, que pode ser aberto diretamente no navegador ou incorporado em páginas web.
Valores suportados para size e níveis de cobrança
gpt-image-2 apenas verifica o formato de size; desde que não seja auto ou vazio, deve corresponder ao formato WIDTHxHEIGHT (por exemplo, 1024x1024, 2048x1152, 800x600); qualquer outro formato retornará 400. A cobrança possui apenas dois níveis:
- Preço padrão 1K: entrada em qualquer tamanho recomendado 1K da tabela abaixo ou apelidos comuns 1K do upstream (
1254x1254,1672x941,941x1672— estes são tamanhos reais retornados pelo upstream no nível 1K e, se reutilizados comosize, não alteram o preço). - Outros níveis (1.5×): qualquer tamanho fora do conjunto 1K acima, incluindo os presets 2K / 4K da tabela e quaisquer
WIDTHxHEIGHTpersonalizados.
| Proporção | 1K (Preço padrão) | 2K recomendado (×1.5) | 4K recomendado (×1.5) |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 4:3 | 1536x1024 | 2048x1536 | 3264x2448 |
| 3:4 | 1024x1536 | 1536x2048 | 2448x3264 |
| 16:9 | 1792x1024 | 2048x1152 | 3840x2160 |
| 9:16 | 1024x1792 | 1152x2048 | 2160x3840 |
Você também pode passarsize: "auto"ou omitir o camposize, neste caso o modelo escolherá o tamanho padrão, cobrando pelo preço padrão 1K. No nível 1K, o upstream não garante alinhamento exato de pixels — se você passar1024x1024, pode receber1254x1254, mantendo a proporção. Se reutilizar este valor comosize, ainda será cobrado como 1K. Chamadas 4K geralmente levam 4–8 minutos; recomenda-se usar o mecanismo de callback assíncronocallback_urldescrito adiante.
Sobre o parâmetroA seguir, alguns exemplos reais para demonstrar as capacidades dongpt-image-2atualmente não suportan > 1: este parâmetro será silenciosamente ignorado; independentemente de passarn=1oun=10, cada requisição retorna apenas 1 imagem e cobra por 1 imagem. Se precisar de múltiplas imagens candidatas, faça múltiplas requisições concorrentes (recomenda-se variarpromptouseedpara evitar imagens muito semelhantes). Essa restrição também se aplica agpt-image-1/gpt-image-1.5e à sérienano-banana. Odall-e-2é o único modelo que suporta nativamenten > 1;dall-e-3suporta apenasn = 1.
gpt-image-2.
Cenário 1: Retrato cinematográfico
No prompt, podem ser usados termos cinematográficos (filme 35mm, profundidade de campo rasa, luzes neon etc.) para controlar atmosfera e textura com precisão. Exemplo em Python:
Cenário 2: Pôster de viagem vintage (com renderização de texto)
gpt-image-2 apresenta estabilidade na tipografia e layout, ideal para pôsteres, menus, cartões com texto.

AMALFI e ITALIA 1958 claros e corretos.
Cenário 3: Composição complexa e contagem
Este prompt testa a capacidade do modelo de seguir instruções estruturadas sobre quantidade e posição.
dall-e-3.
Cenário 4: Estilo ilustração (paisagem)
Especificando mídia artística e palavras-chave de emoção, o modelo gera ilustrações estilizadas.
Assíncrono e Callback
Chamadas aogpt-image-2 normalmente levam 60–90 segundos. Para evitar conexões longas, pode-se usar o mecanismo de callback assíncrono callback_url, com fluxo idêntico a outros modelos.
Série Nano Banana
A sérienano-banana é baseada no modelo Gemini e integrada pela mesma interface /openai/images/generations, sem necessidade de trocar endpoint; basta alterar o campo model para qualquer um da tabela abaixo.
| Modelo | Cobrança (Créditos / chamada) | Cenário de uso |
|---|---|---|
nano-banana | 0.14 | Geração comum, mais rápida e barata |
nano-banana-2 | 0.28 | Qualidade e detalhes significativamente melhores |
nano-banana-pro | 0.35 | Top da linha, melhor composição, detalhes e texto |
Importante: parâmetros suportados Nano Banana adapta o protocolo OpenAI, mas suporta apenas os parâmetros:model,prompt,size.
sizeé mapeado paraaspect_ratiointerno conforme tabela abaixo; tamanhos não listados são convertidos para1:1:
1024x1024/512x512/256x256→1:11792x1024→16:91024x1792→9:16- Não suporta
n,quality,style,response_format,background,output_format; se passados, são ignorados.- A resposta segue o formato OpenAI (
data[].url), mascreatedé sempre0, não retornab64_json, erevised_prompté igual ao prompt original.
Chamada básica

Upgrade para modelo topo de linha nano-banana-pro
Basta alterar model para nano-banana-pro, mantendo os demais parâmetros:

Callback assíncrono
O mecanismocallback_url funciona igualmente para nano-banana, com fluxo idêntico a outros modelos, conforme seção Callback assíncrono.
Uso básico
Você pode preencher os campos na interface conforme mostrado:
authorization (selecionado no dropdown), model (modelo OpenAI DALL-E a ser usado; há 1 modelo principal disponível), e prompt (texto para gerar a imagem).
À direita, o código de chamada correspondente é gerado, que pode ser copiado e executado, ou você pode clicar em “Try” para testar diretamente.

created: ID único da tarefa de geração.data: contém informações do resultado da imagem.
data[].url é o link para a imagem gerada, que pode ser visualizado como mostrado:

Parâmetro de qualidade da imagem quality
Você pode configurar parâmetros detalhados da geração, como a qualidade da imagem. O parâmetro quality tem dois valores: standard para imagens padrão e hd para imagens com detalhes mais finos e maior consistência.
Exemplo definindo quality como standard:


quality = standard:

quality = hd, obtém-se a imagem abaixo:

hd apresenta detalhes mais finos e maior consistência.
Parâmetro de tamanho da imagem size
Também é possível configurar o tamanho da imagem gerada.
Exemplo definindo tamanho 1024x1024:


1024x1024:

1792x1024:
O tamanho da imagem é visivelmente diferente. Mais tamanhos estão disponíveis na documentação oficial.
Parâmetro de estilo da imagem style
O parâmetro style possui dois valores: vivid para imagens mais vivas e natural para imagens mais naturais.
Exemplo definindo style como vivid:


style = vivid:

style = natural:

vivid gera imagens mais vivas e realistas.
Parâmetro de formato do link da imagem response_format
O parâmetro response_format tem dois valores: b64_json para codificação Base64 do link da imagem, e url para link direto da imagem.
Exemplo definindo response_format como url:



response_format = b64_json, obtém-se a imagem codificada em Base64:
Callback assíncrono
Como a geração de imagens pode levar tempo, a API suporta callback assíncrono para evitar conexões HTTP longas e consumo excessivo de recursos. O fluxo é: o cliente envia a requisição com o campo adicionalcallback_url. A API retorna imediatamente um resultado contendo task_id. Quando a tarefa é concluída, o resultado da geração é enviado via POST JSON para o callback_url informado, incluindo o task_id para associação.
Exemplo prático:
O Webhook é um serviço HTTP que recebe requisições; o desenvolvedor deve substituir pela URL do seu servidor HTTP. Para demonstração, usamos o site público https://webhook.site/, que gera uma URL de webhook, como mostrado:
Copie esta URL, por exemplo https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Configure o campo callback_url com esta URL e preencha os demais parâmetros:
task_id permite associar o resultado à requisição original.
Tratamento de erros
Se ocorrer erro na chamada da API, serão retornados códigos e mensagens correspondentes, por exemplo:400 token_mismatched: requisição inválida, possivelmente parâmetros ausentes ou incorretos.400 api_not_implemented: requisição inválida, possivelmente parâmetros ausentes ou incorretos.401 invalid_token: não autorizado, token inválido ou ausente.429 too_many_requests: muitas requisições, limite de taxa excedido.500 api_error: erro interno do servidor.

