API GPT Image 2.5 em Python: um exemplo que funciona

Para chamar a API GPT Image 2.5, faça um POST para https://api.seedrouter.ai/v1/images/generations com um ID de modelo como gpt-image-2.5-flare e um prompt, guarde o id da tarefa que vem na resposta e consulte GET /v1/tasks/{id} até o status ser completed. A tarefa concluída traz as URLs das suas imagens. O mesmo endpoint cuida de texto para imagem, edições com referência e edições com máscara.

Este guia é um caminho completo e executável em Python, com o equivalente em JavaScript, seguido dos erros mais comuns e do que cada um significa.

Do que você precisa antes da primeira requisição?

Duas coisas: uma chave de API e um ID de modelo.

Crie uma chave em chaves de API e guarde-a em uma variável de ambiente no seu servidor, nunca em código do navegador:

export SEEDROUTER_API_KEY="your-key"

Depois escolha um dos quatro IDs de modelo do GPT Image 2.5. Copie-os exatamente; não existe um ID gpt-image-2.5 sem versão.

Se não souber com qual modelo começar, use o Flare; Flare vs Sunburst explica quando o Sunburst vale a pena.

Como gerar uma imagem com Python?

O envio retorna na hora. A resposta é uma referência de tarefa, não a imagem.

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

Salve task_id antes de fazer qualquer outra coisa. É o único identificador do trabalho pelo qual você acabou de pagar, e é como você se recupera se o seu processo reiniciar enquanto a imagem renderiza.

Como obter a imagem de volta?

Consulte a tarefa a cada poucos segundos até ela terminar. Este loop espera até dez minutos; atingir esse prazo interrompe o seu loop, não a 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}.")

Baixe as URLs que você quer guardar e armazene-as você mesmo. As URLs de resultado são um ponto de entrega, não um armazenamento de longo prazo.

Como fica a mesma chamada em JavaScript?

A requisição é idêntica; só o cliente HTTP muda. Rode no seu servidor para que a chave nunca chegue a um navegador.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

Consulte GET https://api.seedrouter.ai/v1/tasks/${taskId} com o mesmo cabeçalho, exatamente como no loop em Python.

Como editar uma imagem existente?

Adicione imagens de referência à mesma requisição. Não há endpoint de edição separado nem campo de modo: enviar images transforma a requisição em edição, e adicionar uma mask limita a mudança a uma região.

{
  "model": "gpt-image-2.5-sunburst",
  "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"}
}

As entradas precisam ser URLs HTTPS públicas. Você pode enviar até 16 imagens de referência em PNG, JPEG ou WebP com menos de 50 MB cada. A máscara é um PNG com menos de 4 MB, do mesmo tamanho da primeira imagem de referência, e a área transparente dela marca o que mudar. Strings base64, URLs data: e envios de arquivo são rejeitados, então suba os arquivos para o seu próprio armazenamento primeiro e envie as URLs.

Por que a API diz que o modelo não está disponível?

O código de erro 20002 com HTTP 400 (“The requested model is not available.”) significa que o valor de model não é um ID que a API atende. A causa habitual é um quase acerto: gpt-image-2.5 sem a versão, gpt-image-2-5-flare com hífen no lugar do ponto ou um erro de digitação em sunburst. Copie um ID da tabela acima.

Os erros de parâmetro são informados antes de o modelo ser verificado. Se uma requisição também tiver um campo inválido, você recebe 20001 com uma mensagem que indica o campo, por exemplo quality. Corrija isso primeiro; o erro de modelo aparece na próxima tentativa se o ID ainda estiver errado.

Uma tarefa também pode falhar depois de aceita. Essa consulta ainda retorna HTTP 200, com status: "failed" e um objeto error como o código 60001 (política de conteúdo) ou 60002 (falha na geração). Tarefas que falham não são cobradas. O catálogo de erros lista todos os códigos, incluindo os erros de saldo e de limite de taxa, com o próximo passo para cada um.

Perguntas frequentes

Existe uma chamada oficial do SDK de Python que devolve a imagem direto?

Não nesta API. A entrega é assíncrona: você sempre envia, guarda o ID da tarefa e consulta. stream e partial_images não são suportados.

Posso pedir várias imagens de uma vez?

Sim. Defina n de 1 a 10. A tarefa concluída lista uma URL por imagem entregue, e você é cobrado pelas imagens entregues.

Como obter um PNG transparente?

Defina background como transparent e output_format como png. JPEG não tem canal alfa, então essa combinação é rejeitada antes de rodar.

Construa a integração em torno do ID da tarefa

Guarde o ID da tarefa no momento em que recebê-lo, consulte com um prazo e trate um tempo limite de consulta como "ainda rodando", não como "falhou". Todo o resto, incluindo cada campo e limite, está na referência da API GPT Image 2.5, e você pode testar uma requisição sem código no Playground.