dall-e-3, a capacidade de renderização de texto mais forte gpt-image-1, a mais recente geração de gpt-image-2, e a série de modelos nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro que são acessíveis através da mesma interface. Todos eles podem gerar imagens de alta qualidade com base em descrições de texto.
Este documento apresenta principalmente o fluxo de uso da API OpenAI Images Generations, permitindo que utilizemos facilmente as funcionalidades de geração de imagens da série OpenAI.
Fluxo de Solicitação
Para usar a OpenAI Images Generations API, primeiro acesse o console Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro.
Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será retornado automaticamente à página atual.
Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço. A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no console.
📘 Documentação completa: OpenAI Images Generations 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 comparação com dall-e-3 e gpt-image-1 nas seguintes áreas:
- Capacidade de seguir instruções mais forte: capaz de entender com precisão instruções estruturadas complexas sobre composição, contagem, relações de posição, etc.
- Renderização de texto mais clara: em cenários como pôsteres, menus, infográficos, logotipos, o inglês e os números quase não apresentam confusão.
- Expressão de estilo mais rica: suporte nativo a vários estilos, como retratos cinematográficos, pôsteres vintage, ilustrações infantis, fotografia de produtos, infográficos, entre outros.
- Suporte nativo a múltiplas proporções + alta resolução: cobre 5 proporções (1:1, 4:3, 3:4, 16:9, 9:16) com 3 níveis de resolução (1K / 2K / 4K).
model como gpt-image-2. O url no resultado retornado é um link de imagem hospedado permanentemente em platform.cdn.acedata.cloud, que pode ser aberto diretamente no navegador ou incorporado em uma página da web.
Rota de Transmissão Oficial / Variante Reversa (:official / :reverse)
gpt-image-2 utiliza a rota reversa por padrão. Através do sufixo do nome do modelo, é possível escolher explicitamente a rota:
gpt-image-2:official: rota de transmissão oficial. Suportan > 1(retorno de várias imagens de uma vez) e resoluções reais de 2K / 4K, cobrando por imagem, com um preço que é o dobro do preço padrão degpt-image-2. Atualmente, é fornecido apenas pelo canal openai-hk; se a rota não estiver disponível, retornará um erro diretamente, sem rebaixar para a rota reversa.gpt-image-2:reverse: completamente equivalente aogpt-image-2padrão (rota reversa), usado para declarar explicitamente que a rota reversa deve ser utilizada, sem alteração de preço.
A limitação “sobre o parâmetron” abaixo se aplica apenas à rota padrão / reversa;gpt-image-2:officialsuportan > 1e cobra por imagem.
Valores suportados para size
gpt-image-2 apenas verifica o formato de size, desde que não seja auto ou uma string vazia, deve corresponder a LARGURAxALTURA (por exemplo, 1024x1024, 2048x1152, 800x600); qualquer outra forma retornará 400. Todos os tamanhos (1K / 2K / 4K / personalizado) são cobrados uniformemente por imagem, sem aumento de preço por tamanho.
Restrições rígidas para tamanhos personalizados: largura e altura devem ser múltiplos de 16, lado longo ≤ 3840, total de pixels ≤ 8.294.400. Exceder esses limites resultará em rejeição e retorno de 4xx.
Você também pode passarsize: "auto"ou omitir o camposize, e o modelo escolherá o tamanho padrão. Na faixa de 1K, a saída do upstream não garante alinhamento de pixels rigoroso — você pode passar1024x1024e receber1254x1254, mantendo a proporção. Se você passar isso novamente comosize, a cobrança não muda. Chamadas únicas de 4K geralmente levam de 4 a 8 minutos, recomenda-se usar em conjunto com ocallback_urlpara callbacks assíncronos.
Sobre o parâmetroAbaixo, apresentamos alguns exemplos reais de diferentes ângulos para sentir intuitivamente a capacidade dongpt-image-2atualmente não suportan > 1: esse parâmetro será ignorado silenciosamente, independentemente de você passarn=1oun=10, uma única solicitação retornará apenas 1 imagem e será cobrada apenas por 1 imagem. Se você precisar obter várias imagens candidatas de uma vez, por favor inicie várias solicitações em paralelo (recomenda-se passar diferentespromptou diferentesseed, caso contrário, as imagens obtidas podem ser altamente semelhantes). Essa limitação também se aplica agpt-image-1/gpt-image-1.5, bem como à sérienano-banana/nano-banana-2-lite/nano-banana-2/nano-banana-pro.dall-e-2é atualmente o único modelo que suporta nativamenten > 1;dall-e-3suporta apenasn = 1.
gpt-image-2.
Cenário 1: Retrato Cinemático
Palavras-chave podem usar termos cinematográficos (filme de 35mm, profundidade de campo rasa, luz de néon, etc.) para controlar com precisão a atmosfera e a textura. Código de exemplo de chamada em Python:
Cena Dois: Pôster de Viagem Vintage (com Renderização de Texto)
gpt-image-2 se destaca na tipografia e renderização de fontes, sendo muito adequado para gerar pôsteres, menus, cartões comemorativos e outros designs com texto.
url do resultado retornado é a seguinte:
AMALFI e ITALIA 1958.
Cena Três: Composição Complexa e Contagem
O seguinte prompt é usado para testar a capacidade do modelo de seguir instruções estruturadas sobre “quantidade” e “posição”.
dall-e-3.
Cena Quatro: Estilo de Ilustração (Horizontal)
Ao especificar a mídia artística e palavras-chave emocionais, é possível guiar o modelo a produzir ilustrações estilizadas.
Assíncrono e Callback
gpt-image-2 normalmente requer de 60 a 90 segundos para uma única chamada. Se não desejar manter uma conexão longa, pode-se usar o mecanismo de callback assíncrono callback_url que será apresentado posteriormente, o fluxo de chamada é idêntico ao de outros modelos.
Série de Modelos Nano Banana
A sérienano-banana é um modelo de geração de imagens baseado no Gemini, que já está integrado através do mesmo endpoint /openai/images/generations, sem necessidade de mudar o endpoint, basta alterar o model para qualquer um dos listados na tabela abaixo.
Importante: Faixa de suporte de parâmetros O Nano Banana se conecta ao protocolo OpenAI através de uma camada de adaptação, e em comparação comgpt-image-*, suporta apenas os seguintes parâmetros:model,prompt,size.
sizeserá mapeado paraaspect_ratiointerno conforme a tabela abaixo, tamanhos não listados serão degradados para1:1:
1024x1024/512x512/256x256→1:11792x1024→16:91024x1792→9:16- Não suporta parâmetros como
n,quality,style,response_format,background,output_format, etc.; se preenchidos, serão ignorados.- A estrutura de retorno segue o formato OpenAI (
data[].url), mascreatedé fixo em0, e não retornaráb64_json,revised_promptsempre será igual ao prompt original.
Chamada Básica
url 字段访问：
Upgrade para o modelo flagship nano-banana-pro
Basta alterar model para nano-banana-pro, os demais parâmetros permanecem os mesmos:
Callback assíncrono
O mecanismo de callback assíncronocallback_url é igualmente eficaz para o nano-banana, o fluxo de chamada é idêntico ao de outros modelos, consulte a seção Callback assíncrono abaixo.
Uso básico
A seguir, você pode preencher o conteúdo correspondente na interface, como mostrado na imagem:
authorization, que pode ser selecionado diretamente na lista suspensa. O outro parâmetro é model, que é a categoria do modelo que escolhemos usar do site oficial do OpenAI DALL-E, aqui temos principalmente 1 tipo de modelo, mais detalhes podem ser vistos nos modelos que fornecemos. O último parâmetro é prompt, que é a palavra-chave que inserimos para gerar a imagem.
Você também pode notar que à direita há um código de chamada correspondente gerado, você pode copiar o código e executá-lo diretamente, ou pode clicar no botão “Try” para testar.
created, ID gerado para esta geração de imagem, usado para identificar exclusivamente esta tarefa.data, contém as informações do resultado da geração da imagem.
data inclui as informações específicas da imagem gerada pelo modelo, e o url é o link detalhado da imagem gerada, como pode ser visto na imagem abaixo.
Parâmetro de qualidade da imagem quality
A seguir, vamos apresentar como definir alguns parâmetros detalhados do resultado da geração da imagem, onde o parâmetro de qualidade da imagem quality contém duas opções, a primeira standard indica a geração de uma imagem padrão, e a outra hd indica que a imagem criada possui detalhes mais refinados e maior consistência.
Abaixo, definimos o parâmetro de qualidade da imagem como standard, as configurações específicas estão na imagem abaixo:
standard é mostrada na imagem abaixo:
hd ，可以得到如下图所示的图片：
hd 比 standard 生成的图片具有更精细的细节和更大的一致性。
图片大小尺寸参数 size
我们还可以设置生成图片的尺寸大小，我们可以进行下面的设置。
下面设置图片的尺寸大小为 1024 * 1024 ，具体设置如下图：
1024 * 1024 的生成图片如下图所示：
1792 * 1024 ，可以得到如下图所示的图片：
可以看到图片的尺寸大小很明显不一样，另外还可以设置更多尺寸大小，详情信息参考我们官网文档。
图片风格参数 style
图片风格参数 style 包含俩个参数，第一种 vivid 表示生成的图片是更加生动的，另一种 natural 表示生成的图片更加的自然一点。
下面设置图片风格参数为 vivid ，具体设置如下图：
vivid 的生成图片如下图所示：
natural ，可以得到如下图所示的图片：
vivid 比 natural 生成的图片具有更加生动逼真。
图片链接的格式参数 response_format
最后一个图片链接的格式参数 response_format 也有俩种，第一种 b64_json 是对图片链接进行 Base64 编码，另一种 url 就是普通的图片链接，可以直接查看图片。
下面设置图片链接的格式参数为 url ，具体设置如下图：
url é URL da imagem que pode ser acessada diretamente, o conteúdo da imagem é mostrado na figura abaixo:
b64_json, e pode-se obter o resultado do link da imagem codificado em Base64, o resultado específico é mostrado na figura abaixo:
Callback Assíncrono
Como a API de Gerações de Imagens da OpenAI pode levar um tempo relativamente longo para gerar imagens, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema, portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campocallback_url adicional, após o cliente fazer a solicitação à API, a API retornará imediatamente um resultado, contendo um campo de informação task_id, representando o ID da tarefa atual. Quando a tarefa for concluída, o resultado da imagem gerada será enviado para o callback_url especificado pelo cliente em formato JSON POST, que também incluirá o campo task_id, assim o resultado da tarefa pode ser associado pelo ID.
Vamos entender como operar isso através de um exemplo.
Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP, os desenvolvedores devem substituí-lo pela URL do servidor HTTP que construíram. Aqui, para facilitar a demonstração, usamos um site de exemplo de Webhook público https://webhook.site/, ao abrir este site, você obterá uma URL de Webhook, como mostrado na figura:
Copie esta URL e você pode usá-la como Webhook, o exemplo aqui é https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Em seguida, podemos definir o campo callback_url para a URL do Webhook acima, ao mesmo tempo preenchendo os parâmetros correspondentes, como mostrado no código abaixo:
task_id, o campo data inclui os mesmos resultados de geração de imagem que a chamada síncrona, e através do campo task_id é possível realizar a associação da tarefa.
Tratamento de Erros
Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a informação correspondente. Por exemplo:400 token_mismatched：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.400 api_not_implemented：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.401 invalid_token：Não autorizado, token de autorização inválido ou ausente.429 too_many_requests：Muitas solicitações, você excedeu o limite de taxa.500 api_error：Erro interno do servidor, algo deu errado no servidor.