GPT Image 2.5

O GPT Image 2.5 aceita um prompt de texto e, opcionalmente, imagens de referência. Envie uma vez, guarde o identificador de tarefa retornado e consulte essa tarefa para obter as imagens prontas. Ele é oferecido como dois modelos que leem os mesmos parâmetros: Flare para o trabalho do dia a dia e Sunburst quando a precisão nas edições é o que mais importa.

IDs de modelo

Os quatro IDs aceitam os mesmos parâmetros. Os canais diferem na cobrança; veja os preços atuais na página do modelo.

Exemplo rápido

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "An amber glass bottle on a cream background, studio lighting",
    "size": "1024x1024",
    "quality": "low"
  }'

Endpoint

POST https://api.seedrouter.ai/v1/images/generations

O mesmo endpoint atende geração, edição com referência e edição com máscara. A resposta contém um identificador de tarefa, não a imagem pronta. Mantenha as chaves de API em código do servidor.

Parâmetros

Regras de tamanho

As escolhas comuns são 1024x1024, 1536x1024 e 1024x1536. Dimensões personalizadas precisam atender a todas as regras:

• Largura e altura são múltiplos de 16.
• Nenhum lado passa de 3840 pixels.
• A proporção fica entre 1:3 e 3:1.
• A área total fica entre 655.360 e 8.294.400 pixels, inclusive.

auto deixa as dimensões de saída a cargo do modelo. Não envie proporções como 16:9 em size.

O Playground oferece os controles Auto, Proporção e Personalizado. O modo Proporção combina uma proporção com um preset de orçamento de pixels de 1K, 2K ou 4K e envia apenas o size resultante. Esses são presets da interface, não parâmetros separados da API: não envie resolution nem aspect_ratio. Por exemplo, 16:9 + 4K envia size: "3840x2160"; 9:16 + 4K envia "2160x3840"; 1:1 + 2K envia "2048x2048". O arredondamento e o limite de lado podem reduzir a contagem de pixels de um nível escolhido. As dimensões exatas aparecem antes do envio.

A OpenAI descreve resoluções acima de 2560×1440 como experimentais. Elas são aceitas dentro dos limites acima; resolução maior não garante mais detalhe.

Níveis de qualidade

xhigh e max são novidades do GPT Image 2.5; o GPT Image 2 vai só até high. Níveis mais altos levam mais tempo para renderizar e, nos IDs cobrados por tokens, consomem mais tokens de saída. Em uma medição a 1024x1024, uma renderização informou 196, 439, 1.756, 3.122 e 7.024 tokens de saída para low, medium, high, xhigh e max. São amostras observadas, não garantias: o uso também depende do tamanho e do conteúdo.

Use low para rascunhos e compare os resultados antes de escolher um nível mais alto. auto deixa a escolha com o modelo; não garante um nível ou custo específico.

Fundos transparentes

A transparência é suportada no GPT Image 2.5. Para fundo transparente, defina background: "transparent" e use PNG. JPEG não aceita transparência. A compressão se aplica apenas a JPEG.

user está disponível para integrações da API, mas não é exibido nem preenchido automaticamente no Playground.

As configurações escalares opcionais (n, size, quality, background, output_format, output_compression, moderation) aceitam null como omissão. Campos desconhecidos são recusados. input_fidelity não é um parâmetro do GPT Image 2.5. style e response_format pertencem a outros modelos de imagem e não são aceitos aqui.

Modos

Não há parâmetro de modo separado nem endpoint de edição a escolher.

Editar imagens de referência

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Make the bottle blue. Preserve the composition and lighting.",
    "images": [{"image_url": "https://example.com/reference.png"}],
    "mask": {"image_url": "https://example.com/mask.png"},
    "output_format": "jpeg",
    "output_compression": 90
  }'

Substitua as duas URLs de exemplo por imagens suas acessíveis. Omita mask para uma edição com referência sem região selecionada.

Entradas de mídia

Esta API aceita apenas referências por URL. Identificadores do OpenAI Files, data URLs em base64 e envios multipart não são aceitos. O Playground envia os arquivos selecionados para o armazenamento antes de submeter as URLs deles.

As imagens de referência precisam ser URLs HTTP(S) públicas apontando para arquivos PNG, JPEG ou WebP de menos de 50 MB cada. Uma máscara precisa ser um PNG de menos de 4 MB, com as mesmas dimensões da primeira imagem de referência; a área transparente marca o que será editado. A máscara orienta o modelo e não garante bordas exatas em nível de pixel. Com várias referências, a máscara se aplica à primeira imagem. Mídias por URL são validadas durante o processamento; mídias inválidas ou inacessíveis podem fazer a tarefa falhar.

O Playground envia os arquivos selecionados e submete as URLs deles. As requisições da API usam objetos de URL em JSON: não envie bytes de arquivo, base64, URLs data:, URLs blob: nem dados de formulário multipart.

Fatores de custo

Consulte a seção de preços do modelo para as tarifas atuais. Os IDs Standard cobram um preço fixo por imagem entregue, independentemente de qualidade, tamanho ou prompt. Nos IDs Official, o custo final depende do consumo de entrada e saída: qualidade, dimensões de saída, imagens de referência, tamanho do prompt e número de imagens podem afetá-lo.

A estimativa do Playground usa uma amostra medida e as tarifas atuais; não é um orçamento garantido. Consulte as cobranças finais no histórico de uso da sua conta. Tarefas que falham não são cobradas.

Esquema de saída

O envio retorna uma referência de tarefa:

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "processing",
  "created_at": 1789970508
}

Consultar a tarefa

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Consulte em um intervalo moderado, por exemplo a cada três segundos, até que status seja completed ou failed. Um tempo limite de rede durante a consulta não significa que a geração falhou: guarde o identificador da tarefa e retome a verificação. Não crie outra tarefa para acompanhar o progresso.

Exemplo completo de consulta

Execute isto após o exemplo de envio em Python acima. Ele usa o task_id retornado e aguarda até dez minutos. Atingir esse prazo local apenas encerra a consulta; guarde o identificador e retome a consulta da mesma tarefa.

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Tarefa concluída

Uma tarefa concluída retorna as URLs das imagens hospedadas e o uso:

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "completed",
  "created_at": 1789970508,
  "finished_at": 1789970538,
  "output": {
    "created": 1789970532,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
    "usage": {
      "input_tokens": 29,
      "output_tokens": 196,
      "total_tokens": 225
    }
  }
}

Esta API entrega os resultados de forma assíncrona por tarefas. Ela não substitui um SDK de Images síncrono; stream e partial_images não são aceitos.

Erros

Requisições recusadas antes de a tarefa ser criada retornam um erro HTTP com um objeto error. Uma tarefa que falha após ser aceita retorna HTTP 200 na consulta, com status: "failed" e um objeto error.

Veja o catálogo de erros comum para códigos, status HTTP e orientações de nova tentativa. Todas as APIs de modelos usam a mesma estrutura de erro.

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}

Se o próprio envio atingir o tempo limite, verifique seu histórico de tarefas antes de enviar de novo: a primeira requisição pode já ter sido aceita.

Dicas

• Descreva materiais, composição e iluminação no prompt.
• Em uma edição, especifique tanto a mudança quanto o que deve permanecer igual.
• Use uma máscara quando apenas uma área selecionada deve mudar.
• Salve as imagens retornadas no seu próprio armazenamento quando precisar de uma cópia duradoura.

Relacionados

• Playground e preços do GPT Image 2.5
• Baixar o OpenAPI
• Markdown copiável