Skip to main content
O serviço de edição de imagens da OpenAI permite enviar qualquer número de imagens e instruções, retornando as imagens modificadas. Atualmente, a API suporta os modelos dall-e-2, gpt-image-1, o mais recente gpt-image-2, bem como a série de modelos nano-banana / nano-banana-2 / nano-banana-pro integrados pela mesma interface. Este documento apresenta principalmente o fluxo de uso da OpenAI Images Edits API, que facilita o uso oficial da funcionalidade de edição de imagens da OpenAI.

Processo de Solicitação

Para usar a OpenAI Images Edits API, acesse a página OpenAI Images Edits 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, retornará automaticamente para esta página. Na primeira solicitação, há uma cota gratuita concedida para uso da API.

Modelo GPT-Image-2

O gpt-image-2 apresenta melhorias significativas em relação ao gpt-image-1 no cenário de edição de imagens:
  • Manutenção mais estável da estrutura: Ao trocar a pele, cores ou fundo, quase não há destruição da composição e layout originais da imagem.
  • Preservação mais precisa do texto: Imagens contendo texto, como infográficos, pôsteres e menus, mantêm o texto claro e legível após a edição.
  • Suporte a URL direta: Além do tradicional upload de arquivos via multipart/form-data, o gpt-image-2 também suporta a passagem de URLs de imagens em JSON, sem necessidade de baixar a imagem localmente, ideal para integração em pipelines de servidor.
  • Suporte a redimensionamento em alta resolução: É possível enviar uma imagem original de 1K e, via parâmetro size, solicitar saída em 2K ou 4K; o modelo realiza o redimensionamento durante o processo de edição.

Valores suportados para size

As restrições do parâmetro size na interface de edição são idênticas às da interface de geração — o gpt-image-2 aceita size como auto, vazio ou no formato WIDTHxHEIGHT; qualquer outro formato retorna erro 400. Todos os tamanhos (1K / 2K / 4K / personalizados) são cobrados por imagem única, independentemente da resolução original ou do valor solicitado em size. As restrições rígidas do upstream para tamanhos personalizados também se aplicam: largura e altura múltiplos de 16, lado maior ≤ 3840, total de pixels ≤ 8.294.400.
Por exemplo: se a imagem original for 1024x1024 e size for 2048x2048, o modelo redesenhará e retornará uma imagem 2K; se size for 3840x2160, a saída será uma imagem 4K em formato paisagem; se auto ou omitido, o modelo escolherá automaticamente. A cobrança é a mesma para os três casos.
Sobre o parâmetro n Atualmente, a interface de edição do gpt-image-2 não suporta n > 1: esse parâmetro será ignorado silenciosamente; independentemente de enviar n=1 ou n=10, apenas uma imagem será retornada por requisição e cobrada como uma única imagem. Se desejar múltiplas imagens candidatas, faça múltiplas requisições concorrentes. Essa limitação também vale para gpt-image-1 / gpt-image-1.5 e para a série nano-banana. O dall-e-2 é o único modelo de edição que suporta nativamente n > 1.
A seguir, apresentamos dois exemplos reais para demonstrar a capacidade de edição do gpt-image-2.

Modo de chamada 1: JSON + URL da imagem (recomendado)

Envie a requisição com Content-Type: application/json, preenchendo o campo image com a URL da imagem; o modelo buscará a imagem e a editará conforme o prompt. Por exemplo, a imagem original abaixo foi gerada com gpt-image-2 como um infográfico científico:

Queremos alterar para um esquema de cores “modo noturno”. Podemos chamar assim:
Ou em Python:
Resposta:
Imagem editada:

Note que a estrutura dos módulos, divisão das informações e tipografia foram rigorosamente preservadas, apenas o esquema de cores foi invertido para tema escuro.
Dica: o campo image também aceita um array, por exemplo "image": ["url1", "url2", "url3"], com até 16 imagens de referência para o modelo considerar na edição.

Modo de chamada 2: JSON + múltiplas imagens de referência

O gpt-image-2 suporta múltiplas imagens de referência para gerar o resultado final, por exemplo, combinar várias fotos de produtos em uma cesta de presente:

Exemplo de cenário: trocar estilo mantendo estrutura

Outro exemplo: substituir uma estante de madeira por uma prateleira flutuante moderna, mantendo rigorosamente a quantidade e disposição dos livros em cada prateleira. Imagem original (estante de madeira gerada com gpt-image-2):

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

O estilo e ambiente foram completamente substituídos conforme o prompt, mas a quantidade de livros por prateleira (1 / 3 / 7) foi rigorosamente mantida, e uma pequena suculenta foi adicionada conforme solicitado.

Modo de chamada 3: multipart/form-data (compatível com OpenAI SDK)

Se você já usa o SDK oficial OpenAI Python, o método tradicional de upload via multipart/form-data também funciona, basta alterar o model para gpt-image-2:
Ao usar o SDK, é necessário definir duas variáveis de ambiente: OPENAI_BASE_URL para https://api.acedata.cloud/openai e OPENAI_API_KEY para o token obtido:

Série Nano Banana

A série nano-banana também está integrada em /openai/images/edits; basta alterar o model para qualquer um da tabela abaixo.
Importante: parâmetros suportados Nano Banana usa uma camada adaptadora para o protocolo OpenAI, suportando apenas os parâmetros: model, prompt, image.
  • image pode ser enviado via upload multipart/form-data (internamente convertido para data:<mime>;base64,... para o upstream) ou como URL via campo de formulário.
  • Não suporta mask, n, size, response_format e similares; esses parâmetros serão ignorados.
  • A resposta segue o formato OpenAI (data[].url), mas created é sempre 0, não retorna b64_json, e revised_prompt é sempre igual ao prompt original.

Chamada via formulário + URL da imagem

Resposta:
Imagem editada:

Chamada via formulário + arquivo local

Callback assíncrono

O mecanismo de callback assíncrono via callback_url também funciona para nano-banana, com fluxo idêntico aos outros modelos, conforme a seção Callback assíncrono abaixo.

Uso básico

A seguir, um exemplo de chamada via CURL:
Na primeira vez usando essa API, precisamos preencher pelo menos quatro campos: authorization (selecionado na lista suspensa), model (modelo escolhido conforme a lista disponível), prompt (descrição do que gerar) e image (caminho da imagem a ser editada). A imagem a ser editada é a seguinte:

Código Python equivalente para a mesma chamada:
Para usar Python, defina as variáveis de ambiente OPENAI_BASE_URL para https://api.acedata.cloud/openai e OPENAI_API_KEY para o token obtido, por exemplo no Mac OS:
Após a chamada, será gerada uma imagem gift-basket.png no diretório atual, com o seguinte resultado:

Assim, completamos a edição da imagem. Atualmente, a interface Edits suporta três modelos: dall-e-2, gpt-image-1 e gpt-image-2, sendo o gpt-image-2 o modelo recomendado, conforme explicado na seção Modelo GPT-Image-2.

Callback assíncrono

Como a edição de imagens via OpenAI Images Edits API pode levar algum tempo, manter a conexão HTTP aberta pode consumir recursos extras. Por isso, a API oferece suporte a callbacks assíncronos. O fluxo é: o cliente envia a requisição incluindo o campo callback_url; a API retorna imediatamente um resultado contendo o task_id da tarefa. Quando a tarefa for concluída, o resultado da edição será enviado via POST JSON para o callback_url informado, incluindo o task_id para associação. Exemplo prático: Um webhook é um serviço HTTP que recebe requisições; o desenvolvedor deve substituir pelo URL do seu servidor HTTP. Para demonstração, usamos o site público https://webhook.site/, que gera um URL de webhook, como: Copie esse URL, por exemplo https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Em seguida, envie a requisição com o campo callback_url definido para esse URL:
A resposta imediata será:
Após alguns instantes, você poderá ver no webhook o resultado da edição:
Note que o resultado contém o campo task_id e o campo data com o mesmo resultado da chamada síncrona, permitindo associar o resultado à tarefa.

Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará um código e mensagem de erro correspondentes, por exemplo:
  • 400 token_mismatched: Requisição inválida, possivelmente por parâmetros faltantes ou incorretos.
  • 400 api_not_implemented: Requisição inválida, possivelmente por parâmetros faltantes 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

Com este documento, você aprendeu como usar a OpenAI Images Edits API para aproveitar facilmente a funcionalidade oficial de edição de imagens da OpenAI. Esperamos que este guia ajude na integração e uso da API. Em caso de dúvidas, entre em contato com nossa equipe de suporte técnico.