API GPT Image 2.5 in Python: un esempio funzionante

Per chiamare l'API GPT Image 2.5, invia una richiesta POST a https://api.seedrouter.ai/v1/images/generations con un ID modello come gpt-image-2.5-flare e un prompt, conserva l'id dell'attività dalla risposta e interroga GET /v1/tasks/{id} finché lo stato non diventa completed. L'attività completata contiene gli URL delle tue immagini. Lo stesso endpoint gestisce testo-immagine, modifiche con riferimento e modifiche con maschera.

Questa guida è un percorso completo ed eseguibile in Python, con l'equivalente in JavaScript, seguito dagli errori più comuni e dal significato di ciascuno.

Cosa ti serve prima della prima richiesta?

Due cose: una chiave API e un ID modello.

Crea una chiave nella pagina chiavi API e tienila in una variabile d'ambiente sul tuo server, mai nel codice del browser:

export SEEDROUTER_API_KEY="your-key"

Poi scegli uno dei quattro ID modello di GPT Image 2.5. Copiali esattamente; non esiste un ID gpt-image-2.5 senza suffisso.

Se non sai con quale modello iniziare, usa Flare; Flare vs Sunburst spiega quando vale la pena passare a Sunburst.

Come si genera un'immagine con Python?

L'invio risponde subito. La risposta è un riferimento all'attività, non l'immagine.

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"]

Salva task_id prima di fare qualsiasi altra cosa. È l'unico riferimento al lavoro che hai appena pagato, ed è il modo per riprendere se il tuo processo si riavvia mentre l'immagine viene generata.

Come si recupera l'immagine?

Interroga l'attività ogni pochi secondi finché non termina. Questo ciclo attende fino a dieci minuti; raggiungere quella scadenza ferma il tuo ciclo, non l'attività.

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}.")

Scarica gli URL che vuoi conservare e salvali tu stesso. Gli URL dei risultati servono per la consegna, non come archivio a lungo termine.

Com'è la stessa chiamata in JavaScript?

La richiesta è identica; cambia solo il client HTTP. Eseguila sul tuo server, così la chiave non arriva mai a un browser.

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();

Interroga GET https://api.seedrouter.ai/v1/tasks/${taskId} con la stessa intestazione, esattamente come nel ciclo Python.

Come si modifica un'immagine esistente?

Aggiungi immagini di riferimento alla stessa richiesta. Non esiste un endpoint di modifica separato né un campo per la modalità: inviare images la trasforma in una modifica, e aggiungere una mask limita il cambiamento a una zona.

{
  "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"}
}

Gli input devono essere URL HTTPS pubblici. Puoi inviare fino a 16 immagini di riferimento in PNG, JPEG o WebP, ciascuna sotto i 50 MB. La maschera è un PNG sotto i 4 MB, delle stesse dimensioni della prima immagine di riferimento, e la sua area trasparente indica cosa cambiare. Stringhe base64, URL data: e caricamenti di file vengono rifiutati, quindi carica prima i file sul tuo storage e invia gli URL.

Perché l'API dice che il modello non è disponibile?

Il codice di errore 20002 con HTTP 400 («The requested model is not available.») significa che il valore di model non è un ID servito dall'API. La causa tipica è un errore di poco: gpt-image-2.5 senza versione, gpt-image-2-5-flare con un trattino al posto del punto, o un refuso in sunburst. Copia un ID dalla tabella qui sopra.

Gli errori sui parametri vengono segnalati prima del controllo del modello. Se una richiesta ha anche un campo non valido, ricevi 20001 con un messaggio che nomina il campo, per esempio quality. Correggi prima quello; l'errore sul modello compare al tentativo successivo se l'ID è ancora sbagliato.

Un'attività può anche fallire dopo essere stata accettata. Quella interrogazione restituisce comunque HTTP 200, con status: "failed" e un oggetto error come il codice 60001 (policy dei contenuti) o 60002 (generazione non riuscita). Le attività fallite non vengono addebitate. Il catalogo degli errori elenca ogni codice, compresi gli errori di saldo e di limite di frequenza, con il passo successivo per ciascuno.

Domande frequenti

Esiste una chiamata ufficiale dell'SDK Python che restituisce direttamente l'immagine?

Non su questa API. La consegna è asincrona: invii sempre, conservi l'ID attività e interroghi. stream e partial_images non sono supportati.

Posso richiedere più immagini in una volta?

Sì. Imposta n da 1 a 10. L'attività completata elenca un URL per ogni immagine consegnata, e ti vengono addebitate le immagini consegnate.

Come ottengo un PNG trasparente?

Imposta background su transparent e output_format su png. JPEG non ha canale alfa, quindi quella combinazione viene rifiutata prima dell'esecuzione.

Costruisci l'integrazione attorno all'ID attività

Salva l'ID attività nel momento in cui lo ricevi, interroga con una scadenza e tratta un timeout del polling come "ancora in esecuzione" e non come "fallita". Tutto il resto, compresi ogni campo e ogni limite, è nel riferimento API di GPT Image 2.5, e puoi provare una richiesta senza codice nel Playground.