GPT Image 2 / 2.5: geração e edição de imagens

Escolha o endpoint antes de escrever a requisição: text-to-image usa /images/generations; image-to-image usa /images/edits com arquivos de imagem enviados. Mencionar "imagem de referência 1" em um prompt não anexa uma imagem.

Modelos e endpoints

ID do modelo	Text-to-image	Image-to-image
gpt-image-2	/images/generations	/images/edits + arquivos de imagem
gpt-image-2.5-sunburst	/images/generations	/images/edits + arquivos de imagem
gpt-image-2.5-flare	/images/generations	/images/edits + arquivos de imagem

Estes são IDs de modelo distintos. Altere model explicitamente ao trocar de modelo; GPT Image 2.5 não é um alias de GPT Image 2. Verifique a disponibilidade atual e os preços da conta no marketplace.

Operação	Método e endpoint	Formato da requisição
Text-to-image	POST https://apimaster.ai/v1/images/generations	JSON
Image-to-image / edição	POST https://apimaster.ai/v1/images/edits	multipart/form-data com arquivos de imagem reais
Edição de imagem assíncrona	POST https://apimaster.ai/v1/images/edits/async	Mesmos arquivos multipart das edições; retorna um ID de tarefa
Text-to-image assíncrono	POST https://apimaster.ai/v1/images/generations/async	JSON; retorna um ID de tarefa
Consultar uma tarefa	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Autenticação Bearer

Para uma resposta de tarefa de edição de imagem, use /images/edits/async. Envie os mesmos arquivos e campos das edições síncronas e depois consulte /tasks/{task_id}. Não mova uma requisição de edição para generations/async. Esses endpoints de tarefa reutilizam o contrato assíncrono existente: um upstream assíncrono pode retornar sua tarefa prontamente, enquanto um upstream síncrono pode concluir a edição antes que o gateway retorne um ID de tarefa. Eles não são uma promessa de execução imediata em segundo plano. Não use Chat Completions para esses modelos.

Autenticação e tempos limite

Crie uma chave de API e envie Authorization: Bearer YOUR_API_KEY. Requisições JSON de geração usam Content-Type: application/json. Para uploads de arquivos, deixe o cURL ou sua biblioteca HTTP gerar o boundary multipart; não defina manualmente o cabeçalho Content-Type.

Permita pelo menos 180 segundos para requisições básicas, 300 segundos para resoluções mais altas e 600 segundos para edições exigentes ou alta qualidade. Um timeout do cliente não prova que a requisição upstream parou. Evite envios duplicados imediatos.

Text-to-image: geração JSON

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Para Sunburst ou Flare, substitua o ID do modelo por gpt-image-2.5-sunburst ou gpt-image-2.5-flare. Não adicione imagens de referência a este exemplo; use os exemplos de edição abaixo.

Image-to-image: upload de uma referência

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Substitua reference.png por uma imagem local existente. O @ informa ao cURL para enviar os bytes do arquivo; image=reference.png envia apenas uma string com o nome do arquivo. Este padrão de endpoint também se aplica a gpt-image-2 e gpt-image-2.5-sunburst.

Image-to-image: upload de múltiplas referências

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Repita o mesmo campo image[] para cada arquivo, na ordem descrita pelo prompt. n é o número de imagens de saída, não o número de referências. Os limites de referência dependem do modelo selecionado e da rota disponível; não assuma um limite universal de 16 imagens. Comece com uma referência e n=1, depois adicione entradas conforme necessário.

Exemplo de edição em Python

Instale requests. Este exemplo envia um arquivo real e lida com respostas de imagem tanto em URL quanto em base64.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Para vários arquivos, passe uma lista de entradas repetidas de ("image[]", (filename, file_object, mime_type)) para files. Mantenha cada arquivo aberto até que a requisição seja concluída.

Edição de imagem assíncrona

Use este endpoint com GPT Image 2, Sunburst ou Flare quando sua aplicação consumir IDs de tarefa. As regras de upload de arquivos, a ordem das referências, os limites de capacidades e a autenticação são os mesmos das edições síncronas.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

O envio retorna data[0].task_id. Faça o polling usando o mesmo ID de modelo:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Uma tarefa rastreada concluída tem esta forma; todas as imagens geradas são incluídas:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

A tarefa pertence à conta que a enviou. Consulte-a com uma chave de API válida para essa conta. Um envio com falha retorna um erro em vez de uma tarefa utilizável; depois que um ID de tarefa for retornado, continue fazendo o polling dessa tarefa em vez de enviar a edição novamente. Veja a tabela de status de polling abaixo.

Integrações existentes com URL ou base64

Se sua entrada for uma URL, baixe a imagem em sua aplicação e envie seus bytes para /images/edits. Se for um data URI em base64, decodifique o payload em um arquivo ou buffer de bytes e envie-o. Não envie a URL ou o texto base64 como se fosse um upload de arquivo.

Algumas rotas do GPT Image 2 suportam a extensão image_urls em generations. Isso não é um contrato portátil de edição de imagem e não deve ser assumido como funcional no GPT Image 2.5. Novas integrações devem usar os exemplos de edições multipart acima. Uma requisição JSON contendo image_urls, image ou images não equivale ao upload de arquivos para edições.

Parâmetros e limites de capacidades

Campo	Uso
model	Obrigatório; use um ID de modelo exato da tabela acima
prompt	Obrigatório; descreva o resultado e a ordem das referências
image / image[]	Arquivos reais enviados para edições; use PNG ou JPEG nos exemplos básicos
n	Contagem de imagens de saída; comece com 1; o máximo depende da rota
size	Opcional; 1024x1024 é o exemplo básico; outras dimensões de pixel ou proporções dependem da rota
resolution	Extensão opcional específica da rota, como 1k, 2k, 4k; nem todo modelo/rota suporta cada nível
quality	Opcional; valores aceitos e custo dependem da rota
background, output_format, output_compression	Opcional; transparência e codificação de saída exigem suporte da rota
mask	Somente GPT Image 2, quando uma rota de edições disponível suporta máscaras enviadas; não suportado pelo handler multipart atual do GPT Image 2.5

Para o GPT Image 2, o suporte a máscaras deve ser verificado separadamente da edição comum por referência. Uma máscara PNG compatível deve corresponder às dimensões da entrada e incluir um canal alfa. O endpoint multipart atual do GPT Image 2.5 rejeita arquivos de máscara enviados; não adicione uma máscara aos exemplos de Sunburst ou Flare acima. Não presuma que uma solução alternativa JSON com mask_url é suportada sem verificar a rota escolhida.

Envie apenas os campos opcionais de que precisa. Eles podem alterar as rotas elegíveis e o preço; definir um valor padrão explicitamente nem sempre é equivalente a omiti-lo. Nenhuma tabela fixa de tamanhos de pixel ou lista de parâmetros avançados se aplica uniformemente aos três IDs de modelo. O preço real e as capacidades suportadas seguem o marketplace e a resposta da requisição.

Respostas síncronas

Uma geração ou edição bem-sucedida retorna entradas de imagem em data:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

Dependendo da rota e do formato de saída, uma entrada pode conter b64_json em vez disso. Decodifique-a para bytes de imagem. Baixe prontamente as URLs temporárias de resultados. Uma resposta HTTP 200 ou apenas uma contagem de imagens não prova que os detalhes das referências foram preservados; inspecione o resultado em relação à entrada.

Tarefas assíncronas: envio e polling

Para text-to-image, envie JSON sem imagens de referência para generations/async. Para edição de imagem, use o exemplo multipart edits/async acima. Ambos usam o mesmo endpoint de consulta de tarefa:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

O envelope de envio normalmente informa submitted; um upstream já pode reportar um estado de conclusão. A primeira consulta de polling pode já estar concluída. Um ID de tarefa não garante uma resposta imediata: se o upstream selecionado for síncrono, a plataforma aguarda a conclusão da geração antes de retornar a tarefa. Mantenha um tempo limite de envio suficiente.

Faça o polling com o mesmo ID de modelo usado no envio:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status da tarefa	Ação
pending, submitted, processing, in_progress	Aguarde; consulte novamente após 3–5 segundos
succeeded, success, completed	Leia cada entrada em data.result.images; tarefas rastreadas usam um url em string, enquanto respostas upstream legadas podem usar um array de URLs
failed, error, cancelled	Pare o polling e inspecione o erro

Use um prazo geral finito de polling, como 10 minutos. Se expirar, retenha o ID da tarefa para verificações posteriores em vez de criar outra tarefa paga automaticamente. As respostas de consulta de tarefa e as respostas síncronas de imagem têm estruturas diferentes.

Solução de problemas de imagens de referência

1. Verifique se o caminho real da requisição é /v1/images/edits ou /v1/images/edits/async, e não generations ou generations/async.
2. Verifique se o multipart contém bytes de arquivo em image ou image[] repetido, com um boundary gerado. Texto do prompt, nomes de arquivos e contagens de referências não substituem arquivos.
3. Verifique o ID exato do modelo. Uma extensão do GPT Image 2 não é automaticamente suportada pelo Sunburst ou Flare.
4. Se os detalhes de tarefa/log não mostrarem um preview, não conclua que nenhuma imagem foi enviada: os logs podem omitir dados base64 e o conteúdo dos arquivos enviados. Por outro lado, uma contagem de referências registrada no log não estabelece que um upstream usou as imagens.
5. Teste com uma referência simples contendo textos ou formas distintas e peça uma mudança de fundo sem descrever esses detalhes. Compare a saída visualmente.
6. Para suporte, retenha o ID da requisição (X-Oneapi-Request-Id), o ID da tarefa se houver, o modelo, o endpoint, o timestamp, os campos sanitizados da requisição e as imagens de referência. Nunca compartilhe sua chave de API.

Para uma resposta 400, inspecione a compatibilidade de endpoint e parâmetros; 401 indica falha de autenticação; 429 indica um limite de taxa/cota. Para timeouts ou falhas upstream, retenha o ID da requisição/tarefa e verifique a tarefa existente ou o registro de uso antes de reenviar.