OpenAI Images Edits API 申请及使用

OpenAI serviço de edição de imagens permite enviar imagens e instruções, gerando imagens modificadas. O modelo da série GPT Image pode receber até 16 imagens de referência ao mesmo tempo. Atualmente, a interface suporta simultaneamente gpt-image-1, o 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 apresenta principalmente o fluxo de uso da API OpenAI Images Edits, permitindo que utilizemos facilmente a funcionalidade de edição de imagens da OpenAI.

申请流程

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á 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 painel de controle.

📘 Documentação completa: OpenAI Images Edits API →

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 preservado com mais precisão: imagens que contêm 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 multipart/form-data, gpt-image-2 também suporta a entrada de URL de imagem via JSON, sem a necessidade de baixar a imagem localmente, sendo 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 prévio para um servidor de imagens.
Suporte a reedição em alta resolução: é possível enviar uma imagem original de 1K e solicitar saída em 2K / 4K através do parâmetro size, com o modelo ampliando a imagem durante o processo de edição.

线路变体（`:official` / `:reverse`）

gpt-image-2 utiliza a linha padrão por padrão. É possível escolher explicitamente a linha através do sufixo do nome do modelo:

gpt-image-2:official: canal oficial, estável e em conformidade. Os custos são determinados pelo Token de entrada de texto, Token de entrada de imagem durante a edição e Token de saída de imagem, sendo o valor final calculado com base no uso real retornado na resposta; o preço exibido na página para qualidade/tamanho é apenas uma estimativa; com base no pacote de uso máximo, o preço para o cliente é cerca de 80% do preço padrão oficial da OpenAI. O serviço automaticamente tolera falhas entre canais disponíveis, com capacidade e custos baseados nos resultados reais retornados.
gpt-image-2:reverse: completamente equivalente ao gpt-image-2 padrão, com melhor custo-benefício, mantendo o mesmo preço.

:official 计费公式 Custo final = Token de entrada de texto + Token de entrada de imagem (apenas edição) + Token de saída de imagem. O preço exibido de quality × size é uma estimativa antes da solicitação, e a cobrança real é baseada no usage da resposta bem-sucedida. Por exemplo, low, 1024x1024 geralmente custa cerca de 0.0505 Créditos para a saída de imagem, além de um pequeno número de Tokens de entrada; ao usar auto, o modelo pode escolher uma qualidade mais alta, e o limite de pré-autorização será verificado de forma conservadora em um nível mais alto.

支持的 `size` 取值

A validação de formato para o size na interface de edição é a mesma 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. O gpt-image-2 padrão e :reverse cobram de forma unificada por imagem; :official calculará simultaneamente os Tokens de entrada de texto, entrada de imagem de referência e saída de imagem, onde a imagem original, tamanho e qualidade podem influenciar o custo final. Limites de tamanho: tamanhos personalizados devem ter largura e altura como múltiplos de 16, com lado maior ≤ 3840 e total de pixels ≤ 8.294.400; exceder esses limites resultará em erro 4xx.

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 e size é 2048x2048, o modelo irá redesenhar e gerar uma imagem 2K de acordo com as instruções de edição; se size for 3840x2160, a saída será uma imagem 4K em modo paisagem. O gpt-image-2 padrão e :reverse têm a mesma cobrança para os três tamanhos; :official será baseado no uso real de Tokens. Omissão do campo size é equivalente a passar explicitamente auto: gpt-image-2 irá primeiro ler a intenção de tamanho explícita nas instruções, incluindo pixels, proporção, orientação, nível de resolução (por exemplo, 4K / alta resolução) ou nomeação de tela. Quando a intenção de tamanho é identificada, o tamanho específico planejado será adotado; se não houver requisitos de tamanho nas instruções ou se a avaliação automática não for possível, o tamanho da primeira imagem de referência será utilizado. O tamanho final específico será normalizado para múltiplos de 16, respeitando os limites de lado maior e total de pixels antes da submissão da solicitação; para controle absoluto, por favor, passe diretamente LARGURAxALTURA. Após a conclusão da geração, não haverá tentativas automáticas devido a diferentes pixels de saída, evitando custos de geração duplicados. Sobre o parâmetro n A interface de edição gpt-image-2 suporta n > 1: uma única solicitação pode retornar a quantidade correspondente de resultados de edição. Por padrão, gpt-image-2 e :reverse cobram com base no número de sucessos; :official cobra com base no uso real de Tokens da resposta total (valores de n de 1 a 10). Isso 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. Observe que response_format=b64_json suporta apenas n=1, e para n>1, utilize o retorno padrão de URL. Se algumas imagens falharem na geração, apenas a parte bem-sucedida será retornada e cobrada.

A seguir, vamos sentir a capacidade de edição do gpt-image-2 através de dois exemplos reais em diferentes ângulos.

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 irá buscar essa imagem e editá-la de acordo com o prompt. Por exemplo, a imagem original abaixo foi gerada com o gpt-image-2 como um guia de ciências:

Queremos alterá-la para uma paleta de “modo noturno”. Podemos chamar assim:

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": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

Ou usando Python:

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": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

O resultado retornado é o seguinte:

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "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 do módulo, a divisão de 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 possa considerar várias imagens na edição.

Envio direto em base64: O image (e cada item do array) pode ser uma URL ou base64 — data:image/png;base64,... ou base64 puro, adequado para imagens locais que não desejam ser carregadas em um servidor de imagens primeiro. Por exemplo:
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": "Convert this infographic to dark mode.",
    "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

O gpt-image-2 suporta a referência a várias imagens ao mesmo tempo para gerar o resultado final, por exemplo, combinar várias fotos de produtos em uma única cesta de presentes:

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "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 a disposição dos livros em cada prateleira. Imagem original (estante de madeira gerada com gpt-image-2):

Chamada:

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "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) ainda foi rigorosamente mantida, e uma pequena 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 existente também é aplicável, basta alterar model para gpt-image-2:

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:

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 no cenário de edição, basta alterar model para qualquer um dos listados na tabela abaixo.

Modelo	Cobrança (Créditos / vez)	Cenário aplicável
`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 flagship da série, melhor preservação de estrutura, texto e estilo

Importante: Faixa de suporte de parâmetros Nano Banana se conecta ao protocolo OpenAI através de uma camada de adaptação, suportando apenas os seguintes parâmetros: model, prompt, image, n.

image pode ser enviado como arquivo via multipart/form-data (arquivos locais serão automaticamente convertidos para base64), ou pode ser passado como uma string de URL de imagem diretamente no campo do formulário.

Não suporta parâmetros como mask, size, response_format, etc.; se preenchidos, serão ignorados. n > 1 é suportado (1–10), retornará e cobrará pela quantidade correspondente de resultados de edição.

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

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=adicione 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:

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "adicione uma folha verde em cima da maçã"
    }
  ]
}

Imagem editada:

Chamada via formulário + arquivo local

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": "adicione 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 assíncrono callback_url também é eficaz para 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 de chamada usando CURL:

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 nela'

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, model é a categoria do modelo que escolhemos usar no site do OpenAI, aqui temos principalmente 1 tipo de modelo, detalhes podem ser vistos nos modelos que fornecemos. Outro parâmetro é prompt, prompt é a sugestão que inserimos para gerar a imagem. O último parâmetro é image, que é o caminho da imagem a ser editada, a imagem a ser editada é mostrada na figura abaixo:

Dica: image[] pode aparecer várias vezes para enviar várias imagens de referência, por exemplo, -F "image[]=@a.png" -F "image[]=@b.png", os modelos da série GPT Image suportam até 16 imagens (cada uma com no máximo 50MB, nos formatos png/webp/jpg). Exceder a quantidade retornará 400.

Código de exemplo em Python com o mesmo efeito de chamada:

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)

Ao usar Python, precisamos primeiro importar duas variáveis de ambiente, uma OPENAI_BASE_URL, que pode ser definida como https://api.acedata.cloud/openai, e outra variável de credencial OPENAI_API_KEY, cujo valor é obtido a partir de authorization, no Mac OS você pode definir as variáveis de ambiente com o seguinte comando:

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:

这样我们就完成了对图片的编辑操作，目前 Edits 接口共支持 gpt-image-1 和 gpt-image-2 两种模型，其中 gpt-image-2 是当前推荐使用的模型，详见上文 GPT-Image-2 模型一节。

异步回调

由于 OpenAI Images Edits API 编辑图片的时间可能相对较长，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，编辑图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。下面我们通过示例来了解下具体怎样操作。首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，如以下代码所示：

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=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

调用之后，可以发现会立即得到一个结果，如下：

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

稍等片刻，我们可以在 Webhook URL 上观察到编辑图片的结果，内容如下：

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

可以看到结果中有一个 task_id 字段，data 字段包含了和同步调用一样的图片编辑结果，通过 task_id 字段即可实现任务的关联。

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
401 invalid_token：Unauthorized, invalid or missing authorization token.
429 too_many_requests：Too many requests, you have exceeded the rate limit.
500 api_error：Internal server error, something went wrong on the server.

错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 OpenAI Images Edits API 轻松使用官方 OpenAI 的图像编辑功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

OpenAI Images Edits API 申请及使用

申请流程

GPT-Image-2 模型

线路变体（`:official` / `:reverse`）

支持的 `size` 取值

Método de chamada um: JSON + URL da imagem (recomendado)

Método de chamada dois: JSON + várias imagens de referência

Exemplo de cenário: mudar estilo + manter estrutura

Método de chamada três: multipart/form-data (compatível com OpenAI SDK)

Modelos da série Nano Banana

Chamada via formulário + URL da imagem

Chamada via formulário + arquivo local

Callback assíncrono

Uso básico

异步回调

错误处理

错误响应示例

结论

​申请流程

​GPT-Image-2 模型

​线路变体（:official / :reverse）

​支持的 size 取值

​Método de chamada um: JSON + URL da imagem (recomendado)

​Método de chamada dois: JSON + várias imagens de referência

​Exemplo de cenário: mudar estilo + manter estrutura

​Método de chamada três: multipart/form-data (compatível com OpenAI SDK)

​Modelos da série Nano Banana

​Chamada via formulário + URL da imagem

​Chamada via formulário + arquivo local

​Callback assíncrono

​Uso básico

​异步回调

​错误处理

​错误响应示例

​结论

申请流程

GPT-Image-2 模型

线路变体（`:official` / `:reverse`）

支持的 `size` 取值

Método de chamada um: JSON + URL da imagem (recomendado)

Método de chamada dois: JSON + várias imagens de referência

Exemplo de cenário: mudar estilo + manter estrutura

Método de chamada três: multipart/form-data (compatível com OpenAI SDK)

Modelos da série Nano Banana

Chamada via formulário + URL da imagem

Chamada via formulário + arquivo local

Callback assíncrono

Uso básico

异步回调

错误处理

错误响应示例

结论