> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API Solicitação e Uso > OpenAI generation API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentação Completa: [OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits) ## 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. | Proporção | 1K Recomendado | 2K Recomendado | 4K Recomendado | | --------- | -------------- | -------------- | -------------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | > 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: ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Converta esta infografia para o modo escuro: fundo azul marinho escuro, texto creme claro, cartões de módulo arredondados cinza profundo com sombras suaves. Mantenha todo o layout, estrutura e arranjo dos módulos idênticos — apenas inverta o esquema de cores.", "size": "1024x1536" }' ``` ou use Python: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png", "prompt": "Converta esta infografia para o modo escuro: fundo azul marinho escuro, texto creme claro, cartões de módulo arredondados cinza profundo com sombras suaves. Mantenha todo o layout, estrutura e arranjo dos módulos idênticos — apenas inverta o esquema de cores.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` O resultado retornado é o seguinte: ```json theme={null} { "success": true, "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753", "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8", "created": 1777048863, "data": [ { "revised_prompt": "Converta esta infografia para o modo escuro: fundo azul marinho escuro, texto creme claro, cartões de módulo arredondados cinza profundo com sombras suaves. Mantenha todo o layout, estrutura e arranjo dos módulos idênticos — apenas inverta o esquema de cores.", "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png" } ], "elapsed": 83.859 } ``` 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: > > ```python theme={null} > import base64, requests > b64 = base64.b64encode(open("input.png", "rb").read()).decode() > payload = { > "model": "gpt-image-2", > "image": f"data:image/png;base64,{b64}", > "prompt": "Converta esta infografia para o modo escuro.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### 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: ```python theme={null} payload = { "model": "gpt-image-2", "image": [ "https://example.com/item1.png", "https://example.com/item2.png", "https://example.com/item3.png" ], "prompt": "Combine todos os itens acima em uma única cesta de presentes 'Relax & Unwind' em um fundo branco limpo, fotorealista, com iluminação natural suave.", "size": "1024x1024" } ``` ### 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: ```python theme={null} payload = { "model": "gpt-image-2", "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png", "prompt": "Substitua a estante de madeira por uma prateleira flutuante branca moderna montada em uma parede azul pastel. Mantenha o mesmo arranjo exato de livros (1 livro em cima, 3 no meio, 7 embaixo). Adicione uma pequena suculenta em um vaso na prateleira de cima ao lado do livro. Luz do dia brilhante e arejada vindo da esquerda.", "size": "1024x1024" } ``` 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`: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() result = client.images.edit( model="gpt-image-2", image=[open("test.png", "rb")], prompt="Converta esta imagem para o modo escuro enquanto mantém o layout intacto." ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) with open("edited.png", "wb") as f: f.write(image_bytes) ``` 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: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` ## 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. | Modelo | Cobrança (Créditos / vez) | Cenário de Aplicação | | -------------------- | ------------------------- | ----------------------------------------------------------------------------- | | `nano-banana` | 0.14 | Edição de imagem comum, mais rápida e com menor custo | | `nano-banana-2-lite` | 0.14 | Modelo de imagem leve Gemini 3.1, suporta apenas 1K, edição de baixa latência | | `nano-banana-2` | 0.28 | Qualidade e detalhes significativamente melhorados | | `nano-banana-pro` | 0.35 | O modelo principal da série, melhor preservação de estrutura, texto e estilo | > **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:;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 ```shell theme={null} curl -X POST "https://api.acedata.cloud/openai/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=nano-banana" \ -F "prompt=adicionar uma folha verde em cima da maçã" \ -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` O resultado retornado é o seguinte: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "adicionar uma folha verde em cima da maçã" } ] } ``` Imagem editada:

### Chamada via formulário + arquivo local ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/edits" headers = { "authorization": "Bearer {token}" } files = { "image": open("apple.png", "rb"), } data = { "model": "nano-banana-pro", "prompt": "adicionar uma folha verde em cima da maçã" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### 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: ```curl theme={null} curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F 'prompt=Crie uma linda cesta de presentes com estes itens dentro' ``` 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: ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Gere uma imagem fotorrealista de uma cesta de presentes em um fundo branco rotulada 'Relax & Unwind' com uma fita e fonte parecida com caligrafia, contendo todos os itens nas imagens de referência. """ result = client.images.edit( model="gpt-image-1", image=[ open("test.png", "rb") ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # Salvar a imagem em um arquivo with open("gift-basket.png", "wb") as f: f.write(image_bytes) ``` 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: ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` 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](#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/](https://webhook.site/), ao abrir este site, você obterá uma URL de Webhook, conforme mostrado na imagem: ![](https://cdn.acedata.cloud/cjjfly.png) 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: ```shell theme={null} curl -X POST "https://api.acedata.cloud/v1/images/edits" \ -H "Authorization: Bearer {token}" \ -F "model=gpt-image-1" \ -F "image[]=@test.png" \ -F "prompt=Crie uma linda cesta de presentes com estes itens dentro" \ -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" ``` Após a chamada, podemos notar que receberemos imediatamente um resultado, como abaixo: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Após alguns instantes, podemos observar o resultado da edição da imagem na URL do Webhook, com o seguinte conteúdo: ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "b64_json": "iVBORw0KGgo..." } ] } } ``` 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 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 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.