A API de edição de imagens OpenAI altera uma imagem existente a partir de um prompt. A rota nativa é POST /v1/images/edits; ela aceita uma imagem, um prompt e controles de edição opcionais, como uma máscara ou imagens de referência. Use a API de Imagens para uma solicitação específica e use a API de Respostas quando o produto precisar de um fluxo de trabalho de imagem com várias etapas.
Uma edição confiável é um pequeno fluxo de trabalho: congelar o arquivo de origem, definir o que deve permanecer, definir o que pode ser alterado, inspecionar os bytes retornados e salvar o recurso aprovado. Se você preferir alternar entre modelos de imagem e outras ferramentas de mídia em um único espaço de trabalho, Crie e edite imagens com o GPT Image 2 em GlobalGPT; sua API pública utiliza um contrato de tarefa assíncrona diferente, que este guia distingue do endpoint nativo do OpenAI.
Resposta rápida: escolha a abordagem antes de escrever o código
| Necessidade | Rota | Solicitar formato | Resultado a ser tratado |
|---|---|---|---|
| Uma geração ou edição de imagem | API de imagem da OpenAI | POST /v1/images/edits, formulário com várias partes | data[0].b64_json; decodificá-la e armazená-la |
| Várias voltas com contexto de imagem | API de respostas OpenAI | POST /v1/responses com ferramenta de geração de imagens | Extrair o item de saída da geração de imagens |
| Vários perfis de mídia social associados a uma única conta | API pública GlobalGPT | POST /tasks, em seguida, fazer a sondagem GET /tasks/{id} | output.url; salve-o antes que o prazo de 30 dias termine |
Os nomes dos endpoints parecem semelhantes, mas os corpos das solicitações e o tratamento dos resultados não são intercambiáveis.
O que a API de edição de imagens OpenAI faz?
O processo de edição começa com uma imagem existente. Sua solicitação descreve a alteração, enquanto a imagem de entrada fornece o contexto visual que deve ser mantido após a edição. Você pode substituir um plano de fundo, adicionar ou remover um elemento, fazer uma reformulação mais ampla ou passar mais de uma imagem como referência. O modelo ainda interpreta a solicitação; a API não é um editor de pixels com um limite de seleção garantido.
O documento OpenAI descreve dois fluxos de trabalho úteis. O API de imagens é a opção ideal quando uma solicitação deve retornar uma imagem. O API de respostas é a opção mais adequada quando um usuário analisa o resultado, solicita outra alteração e mantém o contexto da imagem ao longo das iterações. Essa escolha afeta tanto a estrutura da solicitação quanto o código que extrai o resultado.
API de Imagens versus API de Respostas
| Pergunta | API de imagens | API de respostas |
|---|---|---|
| Ideal para | Uma única ação de geração ou edição | Uma experiência de edição em várias etapas |
| Entrada típica | Imagem em várias partes, prompt, máscara opcional | Entrada de conversação e ferramenta de geração de imagens |
| Tratamento da saída | data[0].b64_json | Encontre o item de saída da geração de imagens |
| Detalhes dos custos | A edição direta utiliza as taxas atuais de entrada/saída | As regras de entrada armazenadas em cache podem variar; verifique os preços atuais |
Faça uma primeira edição usando a API nativa do OpenAI
Mantenha a chave da API no seu servidor e carregue-a a partir de uma variável de ambiente. O exemplo abaixo envia uma imagem e um prompt para o endpoint de edições documentado. O imagem[] O campo pode ser repetido quando o modelo selecionado suporta várias entradas. O pipeline do shell decodifica a primeira imagem em base64 retornada, convertendo-a em um arquivo PNG local.
Edição nativa do Curl: salvar o resultado em formato b64_json
curl -s \
-X POST "https://api.openai.com/v1/images/edits" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F "model=gpt-image-2.5-sunburst" \
-F "image[]=@source.png" \
-F "prompt=Substitua apenas o fundo por uma cena de estúdio em bege quente; mantenha o produto e a etiqueta inalterados." \
| jq -r '.data[0].b64_json' \
| base64 --decode > edited.pngEdição do SDK do Python: decodificar os bytes retornados
from openai import OpenAI
import base64
client = OpenAI()
result = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("source.png", "rb"),
prompt="Substitua apenas o fundo por um cenário de estúdio em bege quente; mantenha o produto e a etiqueta inalterados.",
)
image_bytes = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as output:
output.write(image_bytes)Antes de considerar essa produção pronta, verifique o arquivo decodificado: confira seu tipo MIME, dimensões, número de bytes e se os detalhes visuais importantes ainda estão presentes. Uma resposta 200 apenas indica que a solicitação foi aceita; ela não garante que a etiqueta, o logotipo ou a geometria do produto tenham sido preservados.
Use máscaras e imagens de referência com segurança
Uma máscara indica ao modelo qual área você deseja alterar, mas o mascaramento de imagens do GPT continua sendo baseado em prompts. O guia do OpenAI alerta explicitamente que o modelo usa a máscara como orientação, e não como um limite absoluto de pixels. Mantenha o prompt específico em relação ao objeto protegido e revise a imagem inteira após a geração.
Verificação prévia da máscara
- A imagem e a máscara utilizam o mesmo formato.
- A imagem e a máscara têm as mesmas dimensões.
- O arquivo da máscara tem menos de 50 MB.
- A máscara contém um canal alfa.
- A instrução indica o que deve permanecer inalterado e o que deve ser substituído.
Verifique a máscara antes de enviá-la
from PIL import Image
source = Image.open("source.png")
mask = Image.open("mask.png")
assert source.format == mask.format, (source.format, mask.format)
assert source.size == mask.size, (source.size, mask.size)
assert mask.width * mask.height > 0
assert mask.mode in {"RGBA", "LA"}, mask.mode
assert mask.fp is None or True # verifique o tamanho do arquivo no disco separadamente
print("source:", source.size, source.format)
print("máscara:", mask.size, mask.mode)Se você passar várias imagens com uma máscara, o guia atual indica que a máscara se aplica à primeira imagem. Essa é uma orientação útil para definir um fluxo de trabalho de referência: defina como primeira entrada o recurso cuja área você pretende editar e trate as imagens restantes como referências, em vez de presumir que a máscara selecione todas elas.
As imagens de referência resolvem um problema diferente. Elas podem fornecer uma identidade para o produto, um tipo de iluminação, uma paleta de cores ou uma orientação de composição. Elas não obrigam o modelo a preservar todos os contornos. Se a forma exata da embalagem ou o rótulo precisarem permanecer inalterados, utilize uma etapa de revisão visual ou uma etapa de edição convencional após a geração do modelo.
Escolha o modelo e os parâmetros
A lista atual do guia de imagens OpenAI inclui gpt-image-2.5-sunburst, gpt-image-2.5-flare, e gpt-image-2. Trate os nomes dos modelos e as opções compatíveis como documentação em constante atualização: verifique a página do modelo imediatamente antes de integrá-los e marque uma versão datada se a reprodutibilidade for importante.
Decisões sobre parâmetros que evitam falhas evitáveis
| Decisão | Regra prática | Por que é importante |
|---|---|---|
| Fidelidade da entrada | Omitir fidelidade_de_entrada para gpt-image-2; suas entradas de imagem são processadas com alta fidelidade. | O envio de um campo não compatível pode transformar uma edição válida em uma solicitação rejeitada. |
| Qualidade | Documento sobre as rotas 2.5 Sunburst e Flare baixo, médio, alto, xalto, e máx.. | Uma configuração mais alta é uma escolha entre custo e latência, não uma garantia de melhor preservação. |
| Formato | Verifique qual é o formato de saída documentado pelo endpoint atual e, em seguida, analise o arquivo decodificado. | Seu pipeline de armazenamento deve se basear nos bytes e no tipo MIME, e não apenas na opção solicitada. |
| Contexto | Indique o plano de fundo desejado no prompt e utilize a opção de plano de fundo documentada, quando disponível. | O modelo ainda interpreta a cena; mantenha as restrições do objeto explícitas. |
| Referências | Use uma imagem de referência para orientar a identidade, a cor ou a iluminação e definir a função de cada elemento. | Papéis ambíguos das imagens dificultam o diagnóstico do desvio. |
Quanto custa a API de edição de imagens OpenAI?
O OpenAI cobra pelo uso da GPT Image com base em categorias de tokens, em vez de um preço fixo universal por edição. A página atual de preços lista tarifas separadas para entrada de imagem, entrada em cache e saída de imagem. As edições diretas na API de Imagens não recebem o tratamento de entrada em cache documentado para a ferramenta de geração de imagens na API de Respostas; portanto, não copie uma estimativa da API de Respostas para uma chamada direta /v1/imagens/edições orçamento.
Taxas de tokens de imagem publicadas, verificadas em 28/09/2026
| Modelo | Entrada de imagem / 1 milhão de tokens | Entrada de imagem em cache / 1 milhão de tokens | Saída de imagem / 1 milhão de tokens |
|---|---|---|---|
| GPT Image 2.5 | $8 | $2* | $30 |
| Imagem GPT 2 | $4 | $1* | $15 |
*A coluna “cached-input” é exibida para o contexto de preços publicado. O guia de preços indica que o “cached-input” se aplica à ferramenta de geração de imagens na API de Respostas, e não a solicitações diretas da API de Imagens, como /v1/imagens/edições. As tarifas podem sofrer alterações; faça o cálculo com base nos dados de uso fornecidos para a sua própria solicitação.
Faça uma estimativa transparente com base no uso
def estimate_image_cost(image_input_tokens, image_output_tokens,
input_rate, output_rate):
retorne (image_input_tokens / 1_000_000) * input_rate + \
(image_output_tokens / 1_000_000) * output_rate
# Apenas a título de exemplo: substitua pelos valores de uso em sua resposta.
estimate = estimate_image_cost(
image_input_tokens=250_000,
image_output_tokens=120_000,
input_rate=4,00,
output_rate=15,00,
)
print(f"${estimate:.4f}")Esta fórmula é um exemplo de planejamento, não uma garantia de um valor fixo por imagem. Inclua novas tentativas, armazenamento de arquivos e qualquer uso separado de texto ou ferramentas em seu próprio orçamento. Quando o resultado for importante, mantenha a solicitação, o uso da resposta, o hash do arquivo decodificado e a decisão de aprovação juntos.
O GlobalGPT utiliza um contrato de API de edição de imagens diferente
O Documentação da API GlobalGPT descreve a geração de imagens, vídeos e áudio como tarefas de mídia assíncronas. Sua URL base pública é https://api2.glbgpt.com/ai-api/open/v1. Envie o JSON para /tarefas, pesquisa /tarefas/{id}, e leia output.url após a conclusão bem-sucedida de uma tarefa. O catálogo de modelos lista gpt-image-2 e gpt-image-2.5 como rotas de edição/referência de imagens com até quatro imagens de entrada e proporção da imagem.
Documentação da API pública da S05: Documentação pública sobre o contrato de tarefa assíncrona; este artigo o diferencia do endpoint nativo de edições multiparte do OpenAI.
Catálogo de modelos públicos da S06: Evidências públicas do catálogo de modelos para as rotas do GPT Image e seus limites documentados para tarefas de imagem; verifique os créditos e campos dinâmicos antes da publicação.
Formato da tarefa pública GlobalGPT
BASE="https://api2.glbgpt.com/ai-api/open/v1"
# Opcional: fazer uma estimativa sem criar uma tarefa ou reservar créditos.
curl "$BASE/tasks/estimate" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Mantenha a garrafa e o rótulo inalterados. Substitua apenas o fundo por uma iluminação de estúdio bege quente.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Envie somente após verificar a estimativa.
curl "$BASE/tasks" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: image-edit-example-001" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Mantenha a garrafa e o rótulo inalterados. Substitua apenas o fundo por uma iluminação de estúdio bege quente.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Verifique o ID da tarefa retornada até que haja sucesso ou falha.
curl "$BASE/tasks/TASK_ID" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY"Não cole o arquivo multiparte do OpenAI máscara, fidelidade_de_entrada, tamanho, ou qualidade campos neste JSON e presumir que eles funcionem. A documentação pública atual do GlobalGPT não lista esses campos para essa rota de imagem. Campos não suportados podem ser descartados e exibidos em parâmetros_ignorados, portanto, verifique essa resposta antes de concluir que uma configuração entrou em vigor.
O GlobalGPT reserva créditos quando uma tarefa de mídia é enviada, libera-os quando a tarefa falha e mantém as mídias bem-sucedidas disponíveis por 30 dias, conforme a documentação pública. Salve o ativo retornado em um armazenamento sob seu controle caso a URL precise permanecer ativa por mais tempo. Use o endpoint de estimativa antes de um lote, uma chave de idempotência ao tentar novamente uma solicitação de rede e o ID original da tarefa quando uma consulta estiver apenas lenta.
O que o teste do modelo GlobalGPT revelou
Para tornar essa distinção mais concreta, realizei um teste de API com o modelo GlobalGPT limitado em 28/09/2026, utilizando dois prompts de entrada fictícios e sem referência a marcas, além de dois prompts de edição. Cada tarefa utilizou o GPT Image 2, uma solicitação na proporção 3:2 e a primeira saída válida. As imagens abaixo são evidências do teste do modelo, e não uma sessão da área de trabalho do navegador, um benchmark ou uma garantia de que todas as edições preservarão todos os contornos.
Entrada P00: A imagem original congelada: uma garrafa fictícia sem marca, com uma tampa branca curta e um rótulo curto.
Referência P01: A imagem de referência congelada: utilizada apenas para fins de iluminação e cor, e não como uma segunda identidade do produto.
T01: edição de fundo com uma imagem
Mostrar o prompt completo
Mantenha inalterados a garrafa de cerâmica, a tampa branca curta, o texto fictício do rótulo "NORTH" e "250 ml", as cores, o ângulo da câmera e as proporções da imagem de origem. Substitua apenas o fundo branco puro por um cenário de estúdio interno em tom bege quente, inspirado na luz suave da janela e em sombras delicadas. Não adicione nenhum objeto, logotipo, palavra, marca d’água, pessoa ou rótulo novo. Mantenha a garrafa como o único objeto em uma composição na orientação paisagem com proporção 3:2.
O que isso demonstra: A garrafa continua reconhecível, o rótulo NORTH / 250 ml está visível, e o fundo branco dá lugar a uma cena aconchegante em tons de bege, em ambiente interno, com sombras suaves que parecem vir de uma janela.
Limite: Esta é uma das primeiras saídas válidas. Ela não comprova a preservação exata dos pixels nem a fidelidade geral dos rótulos.
T02: referência de iluminação e cor com duas imagens
Mostrar o prompt completo
Use a imagem de entrada 1 como referência exata do produto e a imagem de entrada 2 apenas como referência para a iluminação bege quente, a temperatura de cor e as sombras suaves do ambiente interno. Mantenha inalterados a forma da garrafa de cerâmica, a tampa branca curta, o texto fictício do rótulo "NORTH" e "250 ml", as cores, o ângulo da câmera e as proporções da imagem de entrada 1. Substitua o fundo branco por um ambiente de estúdio interno em tom bege quente e tranquilo. Não copie nenhum objeto, texto, logotipo, marca d’água, pessoa ou rótulo adicional da imagem de entrada 2. Mantenha a garrafa como o único objeto em uma composição paisagem na proporção 3:2.
O que isso demonstra: O produto e o rótulo NORTH / 250 ml continuam reconhecíveis, enquanto o cenário adota o ambiente aconchegante em tons de bege do P01, com a mesa e a luz que entra pela janela.
Limite: A proporção da tampa da garrafa, o contorno da garrafa e o posicionamento mudaram visivelmente. Não considere isso uma preservação perfeita ou exata da identidade; recorra à comparação manual quando as dimensões da mercadoria precisarem coincidir.
Como utilizar essas evidências: O resultado útil é um processo de revisão repetível. Fixe a URL de entrada, nomeie o objeto protegido, descreva a função de referência, inspecione os bytes retornados e compare o produto aprovado com a fonte antes da publicação. A transferência de estilo pode ser bem-sucedida mesmo que a geometria ainda sofra desvios.
Lidar com erros e respostas lentas
Sintoma → verificação → ação
| Sintoma | Verifique primeiro | Próximo passo seguro |
|---|---|---|
| 401 / erro de autenticação | Chave do lado do servidor, permissões da conta, host do endpoint | Pare e corrija a autenticação; não avalie a qualidade da imagem. |
| 400 / 422 solicitação inválida | ID do modelo, nomes de campos com várias partes, tipo de arquivo, opções não suportadas | Altere apenas o campo indicado pelo erro e, em seguida, mantenha a solicitação original que apresentou falha. |
| 429 / 5xx / capacidade | Se um ID de tarefa foi criado | Se não houver nenhum ID de tarefa, tente novamente uma vez de acordo com sua política; se houver uma tarefa, verifique esse ID. |
| A tarefa permanece na fila ou em processamento | Status, hora da última medição, estimativa do provedor | Faça a consulta em um intervalo definido; não crie uma duplicata enquanto o status for desconhecido. |
| A saída é um objeto JSON salvo como uma imagem | Tipo de conteúdo, primeiros bytes, formato decodificado | Analisar a resposta, decodificar b64_json ou baixar output.url, e depois validar. |
| O parâmetro parece não ter efeito algum | GlobalGPT parâmetros_ignorados e ficha do modelo | Remova os campos não suportados e utilize o contrato específico do modelo. |
Separe as evidências de transporte das evidências de qualidade. Um tempo limite excedido, uma falha no DNS ou uma resposta de capacidade do provedor significam que você não possui uma imagem válida para avaliação. Por outro lado, uma imagem válida com um limite ou rótulo alterado é um resultado visual que deve ser relatado tal como está, mesmo que a composição pareça atraente.
Lista de verificação para edição de imagens em ambiente de produção
- Congelar a fonte: armazenar o arquivo de entrada, as dimensões, o formato e o hash.
- Atribuir funções às imagens: identifique a imagem em questão e quaisquer referências de iluminação, paleta de cores ou composição.
- Cues protegidos contra gravação: liste a marca, a silhueta, as cores e as proporções que precisam ser analisadas.
- Escolha o contrato: Utilize o formato multipart OpenAI para o endpoint de edições nativas ou as tarefas JSON GlobalGPT para sua API de mídia pública.
- Calcular e enviar: utilizar as taxas atuais do OpenAI ou do GlobalGPT
/tarefas/estimativa; adicione uma chave de idempotência para que os envios possam ser repetidos com segurança. - Consultar e decodificar: manter um ID de tarefa, validar o arquivo retornado e salvar os bytes ou a URL em um armazenamento aprovado.
- Aprovar visualmente: compare o resultado com o original antes que ele seja inserido em um catálogo de produtos, anúncio ou página voltada para o cliente.
Se você quiser executar o mesmo processo sem precisar unir painéis de modelos separados, tente Imagem GPT 2 em GlobalGPT. Para a versão do fluxo de trabalho voltada para navegadores, consulte editar imagens na área de trabalho GlobalGPT; para uma discussão mais ampla sobre configuração e preços, consulte Configuração e preços da API de imagens do GPT.
Perguntas frequentes
O que é a API de edição de imagens OpenAI?
Trata-se da rota de edição de imagens em POST /v1/images/edits. Você envia uma imagem de entrada e um prompt, opcionalmente com uma máscara ou imagens de referência, e depois decodifica os dados da imagem retornados. Use a API de Imagens para uma única edição e a API de Respostas quando o produto precisar de uma conversa com várias trocas de mensagens sobre imagens.
A API de edição de imagens OpenAI retorna uma URL pública da imagem?
Os exemplos documentados da API de imagens retornam b64_json. Decodifique esses bytes, valide o arquivo e salve-o em um armazenamento sob seu controle. Não presuma que uma resposta bem-sucedida seja uma URL hospedada em uma CDN.
A máscara de imagem OpenAI representa uma seleção exata de pixels?
Não. Uma máscara orienta uma edição baseada em instruções. O modelo pode alterar os pixels ao redor da área solicitada; portanto, verifique os rótulos, os detalhes do produto, as marcas de segurança e outros elementos que devem permanecer corretos.
Quantas imagens de entrada um editor de imagens pode utilizar?
O guia de imagens atual oferece suporte a várias imagens de entrada para fluxos de trabalho de referência. Para saber o limite exato e o comportamento específico do modelo, consulte a documentação do modelo atual; o número máximo suportado não garante a preservação perfeita em todas as composições.
Posso enviar a solicitação OpenAI /v1/images/edits para o GlobalGPT alterando o parâmetro base_url?
O contrato de mídia pública do GlobalGPT utiliza JSON POST /tasks e, em seguida, GET /tasks/{id}, com imagens e aspect_ratio, desde que o modelo selecionado as aceite. A documentação pública não lista a máscara multipart, o parâmetro input_fidelity, o tamanho nem o contrato de qualidade do OpenAI para essa rota.
Como devo estimar a complexidade de uma tarefa de imagem antes de enviá-la?
Para o GlobalGPT, envie primeiro o mesmo corpo JSON para /tasks/estimate. Isso não cria uma tarefa nem reserva créditos. Para o OpenAI, faça o cálculo com as taxas atuais por milhão de tokens e, em seguida, verifique o uso real na resposta ou no registro de cobrança.
