dall-e-2, gpt-image-1, a mais recente gpt-image-2, e os modelos da série nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro que são acessados pela mesma interface.
Este documento descreve principalmente o fluxo de uso da API OpenAI Images Edits, permitindo que utilizemos facilmente a funcionalidade de edição de imagens da OpenAI.
Fluxo de Solicitação
Para usar a API OpenAI Images Edits, primeiro acesse o Painel de Controle da 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á redirecionado de volta para a 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 painel de controle.
📘 Documentação Completa: OpenAI Images Edits API →
Modelo GPT-Image-2
gpt-image-2 apresenta melhorias significativas em relação ao gpt-image-1 no cenário de edição de imagens:
- Estrutura mais estável: ao trocar pele, cores ou fundo, quase não há destruição do layout e composição da imagem original.
- Texto mais preciso: imagens que contêm texto, como infográficos, pôsteres e menus, mantêm a legibilidade do texto após a edição.
- Suporte a URL direta: além do tradicional upload de arquivos
multipart/form-data,gpt-image-2também suporta a entrada de URLs de imagens via JSON, eliminando a necessidade de baixar as imagens localmente, ideal para integração em pipelines de servidor. - Suporte a base64 direta: de acordo com o padrão oficial, o campo
imagetambém pode receber base64 diretamente (data:image/png;base64,...ou base64 puro), permitindo a edição de imagens locais sem a necessidade de upload para um servidor de imagens. - Suporte a reedição em alta resolução: é possível enviar uma imagem original de 1K e solicitar uma saída de 2K / 4K através do parâmetro
size, com o modelo ampliando a imagem durante o processo de edição.
Rotações oficiais / Variantes reversas (:official / :reverse)
gpt-image-2 utiliza por padrão a rota reversa. É possível escolher explicitamente a rota através do sufixo do nome do modelo:
gpt-image-2:official: rota oficial. Suportan > 1(retorno de várias imagens de uma vez) e verdadeira saída em 2K / 4K, com cobrança por imagem, a um custo de 2 vezes o preço padrão dogpt-image-2. Atualmente, disponível apenas pelo canal openai-hk; se a rota não estiver disponível, retornará um erro sem rebaixar para a rota reversa.gpt-image-2:reverse: equivalente aogpt-image-2padrão (rota reversa), sem alteração de preço.
As restrições sobre o parâmetro “n” a seguir se aplicam apenas à rota padrão / reversa;gpt-image-2:officialsuportan > 1e cobra por imagem.
Valores suportados para size
As restrições da interface de edição para size são idênticas às da interface de geração — gpt-image-2 aceita size como auto, vazio, ou no formato LARGURAxALTURA, qualquer outra forma resultará em um erro 400. Todos os tamanhos (1K / 2K / 4K / personalizado) têm uma cobrança uniforme por imagem, independentemente da resolução da imagem original e do valor solicitado para size.
As restrições rígidas para tamanhos personalizados também se aplicam: largura e altura devem ser múltiplos de 16, lado longo ≤ 3840, total de pixels ≤ 8.294.400.
Por exemplo: se a imagem original é1024x1024, ao passarsizecomo2048x2048, o modelo irá redesenhar e retornar uma imagem 2K; ao passarsizecomo3840x2160, retornará uma imagem 4K em modo paisagem; se passarautoou omitir, o modelo escolherá por conta própria. A cobrança é a mesma para os três casos.
Sobre o parâmetroA seguir, dois exemplos reais de diferentes ângulos para sentir a capacidade de edição donA interface de ediçãogpt-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 opções de edição de uma só vez, inicie várias solicitações em paralelo. Essa limitação também se aplica agpt-image-1/gpt-image-1.5, bem como às sériesnano-banana/nano-banana-2-lite/nano-banana-2/nano-banana-pro.dall-e-2é atualmente o único modelo de edição que suporta nativamenten > 1.
gpt-image-2.
Método de Chamada Um: JSON + URL da Imagem (Recomendado)
Envie a solicitação diretamente no formatoapplication/json, preenchendo o campo image com a URL de uma imagem, o modelo buscará essa imagem e a editará de acordo com o prompt.
Por exemplo, a imagem original abaixo foi gerada com gpt-image-2 como um guia de ciências:


Dica: o campoimagetambém suporta a entrada de um array, por exemplo,"image": ["url1", "url2", "url3"], permitindo enviar até 16 imagens de referência ao mesmo tempo, para que o modelo considere várias imagens ao realizar a edição.
Envio direto em base64:image(e cada item do array) pode ser uma URL ou base64 —data:image/png;base64,...ou base64 puro, adequado para cenários em que você não deseja fazer upload de imagens locais primeiro. Por exemplo:
Método de chamada dois: JSON + várias imagens de referência
gpt-image-2 suporta a referência de várias imagens para gerar o resultado final, por exemplo, combinar várias fotos de produtos em uma única cesta de presentes:
Exemplo de cenário: mudar estilo + manter estrutura
Aqui está outro exemplo, substituindo uma estante de madeira por uma prateleira flutuante moderna, mas mantendo rigorosamente a quantidade e o arranjo de cada prateleira de livros. Imagem original (gerada comgpt-image-2 da estante de madeira):

task_id: e9544dba-727e-44a2-81e1-223d49869380):

Método de chamada três: multipart/form-data (compatível com OpenAI SDK)
Se você já está usando o SDK oficial do OpenAI Python, o método de uploadmultipart/form-data também é aplicável, basta alterar o model para gpt-image-2:
OPENAI_BASE_URL deve ser definido como https://api.acedata.cloud/openai, e OPENAI_API_KEY deve ser definido como o token obtido:
Modelos da série Nano Banana
A sérienano-banana também se conecta ao /openai/images/edits em cenários de edição, 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, suportando apenas os seguintes parâmetros:model,prompt,image.
imagepode ser enviado como arquivo viamultipart/form-data(o worker internamente converte paradata:<mime>;base64,...para enviar ao upstream), ou pode ser passado como uma string de URL de imagem diretamente no campo do formulário.- Não suporta parâmetros como
mask,n,size,response_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 aopromptoriginal.
Chamada via formulário + URL da imagem

Chamada via formulário + arquivo local
Callback assíncrono
O mecanismo de callbackcallback_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
Agora você pode usar o código para fazer chamadas, abaixo está um exemplo usando CURL:authorization, que pode ser selecionado diretamente na lista suspensa. Outro parâmetro é model, que é a categoria do modelo que escolhemos usar no site da OpenAI, aqui temos principalmente 1 tipo de modelo, detalhes podem ser vistos nos modelos que fornecemos. Outro parâmetro é prompt, que é a palavra-chave que inserimos para gerar a imagem. O último parâmetro é image, que precisa ser o caminho da imagem a ser editada, conforme mostrado na imagem abaixo:

OPENAI_BASE_URL, que pode ser configurada como https://api.acedata.cloud/openai, e outra variável de credencial OPENAI_API_KEY, cujo valor é obtido a partir da authorization, que pode ser configurada no Mac OS com os seguintes comandos:
gift-basket.png será gerada no diretório atual, o resultado específico é o seguinte:

dall-e-2, gpt-image-1 e gpt-image-2, sendo que gpt-image-2 é o modelo recomendado atualmente, consulte a seção Modelo GPT-Image-2 acima.
Callback assíncrono
Como a API OpenAI Images Edits pode levar um tempo relativamente longo para editar 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, especifica um campo adicionalcallback_url. Após o cliente fazer a solicitação à API, a API retornará imediatamente um resultado, contendo um campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da edição da imagem será enviado para o callback_url especificado pelo cliente em formato JSON POST, incluindo também o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID.
Abaixo, vamos entender como operar com 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. 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, conforme mostrado na imagem:
Copie esta URL e você poderá 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 em que preenchemos os parâmetros correspondentes, como mostrado no código a seguir:
task_id, e o campo data inclui o mesmo resultado de edição de imagem que a chamada síncrona, permitindo a associação da tarefa através do campo task_id.
Tratamento de Erros
Ao chamar a API, se encontrar um erro, a API retornará o código de erro e a mensagem 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.

