Skip to main content
O OpenAI Images Generations API atualmente suporta vários modelos de geração de imagens, incluindo o clássico 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).
A chamada é idêntica a outros modelos, basta definir o campo 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 como size, 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 WIDTHxHEIGHT personalizados.
Restrições rígidas do upstream para tamanhos personalizados: largura e altura devem ser múltiplos de 16, lado maior ≤ 3840, total de pixels ≤ 8.294.400. Tamanhos fora desse intervalo serão rejeitados com erro 4xx.
Você também pode passar size: "auto" ou omitir o campo size, 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ê passar 1024x1024, pode receber 1254x1254, mantendo a proporção. Se reutilizar este valor como size, ainda será cobrado como 1K. Chamadas 4K geralmente levam 4–8 minutos; recomenda-se usar o mecanismo de callback assíncrono callback_url descrito adiante.
Sobre o parâmetro n gpt-image-2 atualmente não suporta n > 1: este parâmetro será silenciosamente ignorado; independentemente de passar n=1 ou n=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 variar prompt ou seed para evitar imagens muito semelhantes). Essa restrição também se aplica a gpt-image-1 / gpt-image-1.5 e à série nano-banana. O dall-e-2 é o único modelo que suporta nativamente n > 1; dall-e-3 suporta apenas n = 1.
A seguir, alguns exemplos reais para demonstrar as capacidades do 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:
Resposta:
Imagem gerada:

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.
Imagem gerada:

O modelo reproduz fielmente o estilo Art Deco, com os textos 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.
Imagem gerada:

A quantidade de livros (1 / 3 / 7) está exatamente conforme o prompt, algo difícil de conseguir de forma estável na era do 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.
Imagem gerada:

Assíncrono e Callback

Chamadas ao gpt-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érie nano-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.
Importante: parâmetros suportados Nano Banana adapta o protocolo OpenAI, mas suporta apenas os parâmetros: model, prompt, size.
  • size é mapeado para aspect_ratio interno conforme tabela abaixo; tamanhos não listados são convertidos para 1:1:
    • 1024x1024 / 512x512 / 256x2561:1
    • 1792x102416:9
    • 1024x17929: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), mas created é sempre 0, não retorna b64_json, e revised_prompt é igual ao prompt original.

Chamada básica

Resposta:
Imagem gerada:

Upgrade para modelo topo de linha nano-banana-pro

Basta alterar model para nano-banana-pro, mantendo os demais parâmetros:
Resposta:

Callback assíncrono

O mecanismo callback_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:

Na primeira vez, é necessário preencher pelo menos três campos: 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.

Exemplo Python:
Resposta:
Campos retornados:
  • created: ID único da tarefa de geração.
  • data: contém informações do resultado da imagem.
O campo 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:

O código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
Resposta:
Imagem gerada com quality = standard:

Alterando apenas para 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:

O código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
Resposta:
Imagem gerada com tamanho 1024x1024:

Alterando para tamanho 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:

Código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
Resposta:
Imagem gerada com style = vivid:

Alterando para style = natural:

vivid gera imagens mais vivas e realistas. 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:

Código gerado pode ser copiado ou testado clicando em “Try”.

Exemplo Python:
Resposta:
Link da imagem gerada: Imagem URL, acessível diretamente:

Alterando para 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 adicional callback_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:
Resposta imediata:
Após alguns instantes, no Webhook você verá o resultado da geração:
O campo 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.

Exemplo de resposta de erro

Conclusão

Este documento apresentou como usar o OpenAI Images Generations API para acessar facilmente as funcionalidades oficiais de geração de imagens do OpenAI DALL-E. Esperamos que este guia ajude você a integrar e utilizar a API com sucesso. Para dúvidas, entre em contato com nossa equipe de suporte técnico.