Skip to main content
O serviço de edição de imagens da OpenAI permite enviar várias imagens e instruções, retornando as imagens modificadas. Atualmente, a API suporta 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-2 també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 image també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. Suporta n > 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 do gpt-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 ao gpt-image-2 padrã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:official suporta n > 1 e 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 passar size como 2048x2048, o modelo irá redesenhar e retornar uma imagem 2K; ao passar size como 3840x2160, retornará uma imagem 4K em modo paisagem; se passar auto ou omitir, o modelo escolherá por conta própria. A cobrança é a mesma para os três casos.
Sobre o parâmetro n A interface de edição gpt-image-2 atualmente não suporta n > 1: esse parâmetro será ignorado silenciosamente, independentemente de você passar n=1 ou n=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 a gpt-image-1 / gpt-image-1.5, bem como às séries nano-banana / nano-banana-2-lite / nano-banana-2 / nano-banana-pro. dall-e-2 é atualmente o único modelo de edição que suporta nativamente n > 1.
A seguir, dois exemplos reais de diferentes ângulos para sentir a capacidade de edição do gpt-image-2.

Método de Chamada Um: JSON + URL da Imagem (Recomendado)

Envie a solicitação diretamente no formato application/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:

Queremos alterá-la para uma paleta de cores “modo noturno”. Podemos chamar assim:
ou use Python:
O resultado retornado é o seguinte:
A imagem editada é a seguinte:

Pode-se ver que a estrutura dos módulos, a divisão das informações e a tipografia foram rigorosamente mantidas, apenas a paleta de cores foi invertida para um tema escuro.
Dica: o campo image també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 com gpt-image-2 da estante de madeira):

Chamada:
Resultado da edição (task_id: e9544dba-727e-44a2-81e1-223d49869380):

Pode-se ver que o estilo e o ambiente foram completamente substituídos conforme as instruções, mas a quantidade de livros em cada prateleira (1 / 3 / 7) foi rigorosamente mantida, e uma planta suculenta foi adicionada conforme solicitado.

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 upload multipart/form-data também é aplicável, basta alterar o model para gpt-image-2:
Ao usar o SDK, é necessário importar duas variáveis de ambiente, 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érie nano-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.
  • image pode ser enviado como arquivo via multipart/form-data (o worker internamente converte para data:<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), mas created é fixo em 0, e não retornará b64_json, revised_prompt sempre será igual ao prompt original.

Chamada via formulário + URL da imagem

O resultado retornado é o seguinte:
Imagem editada:

Chamada via formulário + arquivo local

Callback assíncrono

O mecanismo de callback callback_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:
Na primeira vez que usar esta interface, precisamos preencher pelo menos quatro conteúdos, um é 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:

Código de exemplo em Python com o mesmo efeito de chamada:
Para usar o Python, precisamos primeiro importar duas variáveis de ambiente, uma 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:
Após a chamada, descobrimos que uma imagem gift-basket.png será gerada no diretório atual, o resultado específico é o seguinte:

Assim, completamos a operação de edição de imagem. Atualmente, a interface Edits suporta três modelos: 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 adicional callback_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:
Após a chamada, podemos notar que receberemos imediatamente um resultado, como abaixo:
Após alguns instantes, podemos observar o resultado da edição da imagem na URL do Webhook, com o seguinte conteúdo:
Podemos ver que o resultado contém um campo 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.

Exemplo de Resposta de Erro

Conclusão

Através deste documento, você já entendeu como usar a API OpenAI Images Edits para utilizar facilmente a funcionalidade de edição de imagens da OpenAI. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.