API do GPT Image 2 em Python: um exemplo completo

Para usar a API do GPT Image 2 em Python, faça um POST da sua requisição para https://api.seedrouter.ai/v1/images/generations com a biblioteca requests, guarde o id da tarefa que ela retorna, consulte /v1/tasks/{id} até a tarefa ficar completed e baixe as URLs de imagem que ela lista. O script abaixo faz os quatro passos em cerca de 40 linhas e salva as imagens em disco.

Ele roda do jeito que está assim que SEEDROUTER_API_KEY estiver definida. Se você ainda não tem uma chave, obtenha uma primeiro.

Como é um script completo do GPT Image 2?

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    response = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
    return response.json()["id"]


def wait(task_id, limit_seconds=600):
    deadline = time.monotonic() + limit_seconds
    while time.monotonic() < deadline:
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] == "completed":
            return [image["url"] for image in task["output"]["data"]]
        if task["status"] == "failed":
            raise RuntimeError(f"{task['error']['code']}: {task['error']['message']}")
        time.sleep(3)
    raise TimeoutError(f"Still running. Resume polling task {task_id}.")


def download(urls, prefix):
    paths = []
    for index, url in enumerate(urls):
        path = f"{prefix}-{index}.png"
        with open(path, "wb") as file:
            file.write(requests.get(url, timeout=60).content)
        paths.append(path)
    return paths


task_id = submit({
    "model": "gpt-image-2",
    "prompt": "A matte ceramic vase on a sunlit table, soft shadows",
    "size": "1024x1024",
    "quality": "low",
    "n": 2,
})
print("task", task_id)
print(download(wait(task_id), "vase"))

Rode com python example.py. Ele imprime primeiro o ID da tarefa e depois os caminhos de dois arquivos PNG, vase-0.png e vase-1.png.

O que cada função faz?

submit envia a requisição e retorna o ID da tarefa. Uma resposta de erro sempre traz um objeto error com um code numérico e uma message, então a exceção diz o que corrigir. Um 400 com código 20001 e a mensagem “Check the size parameter against the API documentation.”, por exemplo, significa que o tamanho violou uma das regras do guia de parâmetros.

wait consulta a cada três segundos até a tarefa terminar. Um prazo do seu lado interrompe o loop, não a tarefa: a renderização continua, e você pode retomar o polling do mesmo ID depois. Uma tarefa que termina como failed gera uma exceção com o código de erro e não é cobrada.

download busca cada URL que a tarefa retornou e grava em disco. As URLs de resultado são um ponto de entrega, não um armazenamento permanente, então salve o que quiser guardar. O exemplo usa requests tanto nos downloads quanto nas chamadas à API; mantenha um único cliente HTTP do começo ao fim em vez de misturar com o urllib da biblioteca padrão.

Como mudar os ajustes da imagem?

Tudo fica no corpo da requisição. Os campos que a maioria das pessoas muda primeiro:

Se você mudar output_format, troque a extensão .png em download para combinar. A lista completa de campos e limites está na referência da API do GPT Image 2.

Como editar uma imagem em Python?

Passe as imagens de referência como URLs na mesma chamada. Não existe endpoint de edição separado; adicionar images transforma a requisição em edição, e uma mask limita a mudança a uma região:

task_id = submit({
    "model": "gpt-image-2",
    "prompt": "Make the vase deep blue. Keep the table and the light unchanged.",
    "images": [{"image_url": "https://example.com/vase.png"}],
})

As URLs precisam ser links HTTPS públicos para arquivos PNG, JPEG ou WebP. Você pode enviar até 16. Arquivos locais e strings base64 são rejeitados, então suba a imagem para o seu próprio armazenamento primeiro e envie a URL.

O que o script deve fazer quando o envio estoura o tempo limite?

Não envie de novo logo em seguida. Um tempo esgotado no POST não prova que a requisição foi rejeitada; a tarefa pode já estar rodando e ter sido cobrada. Confira suas tarefas recentes, ou só tente a requisição de novo depois de confirmar que nenhuma tarefa foi criada. O guia de tarefas explica como distinguir os dois casos.

O polling é diferente: um tempo esgotado durante o polling é inofensivo. Chame wait de novo com o mesmo ID.

Perguntas frequentes

Posso usar o SDK Python da OpenAI no lugar?

Não diretamente. Esta API entrega os resultados de forma assíncrona por meio de um ID de tarefa, enquanto a chamada de imagem do SDK espera a imagem pronta na resposta. Algumas linhas de requests, como acima, cobrem o fluxo inteiro.

Como rodar vários prompts?

Envie cada prompt, guarde todos os IDs de tarefa e depois consulte-os. O guia de geração em lote mostra uma versão que sobrevive a reinícios sem pagar duas vezes.

O gpt-image-2-official precisa de código diferente?

Não. Troque a string de model e nada mais. Os dois IDs aceitam os mesmos campos e retornam a mesma resposta de tarefa; só a cobrança muda.

Guarde o ID da tarefa; o resto é encanamento

Envie, guarde o ID, consulte com um prazo e baixe o que voltar. Esse padrão é a integração inteira. Teste um prompt sem código no Playground do GPT Image 2 antes de automatizá-lo em script.