API GPT Image 2 in Python: un esempio completo

Per usare l'API GPT Image 2 da Python, invia la richiesta in POST a https://api.seedrouter.ai/v1/images/generations con la libreria requests, conserva l'id dell'attività che ricevi, interroga /v1/tasks/{id} finché l'attività non è completed e scarica gli URL delle immagini che elenca. Lo script qui sotto esegue tutti e quattro i passaggi in circa 40 righe e salva le immagini su disco.

Funziona così com'è non appena SEEDROUTER_API_KEY è impostata. Se non hai ancora una chiave, procuratene una prima.

Com'è fatto uno script GPT Image 2 completo?

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

Eseguilo con python example.py. Stampa prima l'ID attività, poi i percorsi di due file PNG, vase-0.png e vase-1.png.

Cosa fa ogni funzione?

submit invia la richiesta e restituisce l'ID attività. Una risposta di errore contiene sempre un oggetto error con un code numerico e un message, quindi l'eccezione ti dice cosa correggere. Un 400 con codice 20001 e messaggio «Check the size parameter against the API documentation.», per esempio, significa che le dimensioni hanno violato una delle regole della guida ai parametri.

wait interroga l'attività ogni tre secondi finché non termina. Una scadenza dal tuo lato ferma il ciclo, non l'attività: la generazione continua e puoi riprendere il polling dello stesso ID più tardi. Un'attività che termina failed solleva un'eccezione con il suo codice di errore e non viene addebitata.

download recupera ogni URL restituito dall'attività e lo scrive su disco. Gli URL dei risultati servono alla consegna, non all'archiviazione permanente, quindi salva ciò che vuoi conservare. L'esempio usa requests sia per i download sia per le chiamate API; mantieni un unico client HTTP invece di mescolarlo con urllib della libreria standard.

Come si cambiano le impostazioni dell'immagine?

Tutto sta nel corpo della richiesta. I campi che si cambiano più spesso per primi:

Se cambi output_format, adegua l'estensione .png in download. L'elenco completo di campi e limiti è nella documentazione dell'API GPT Image 2.

Come si modifica un'immagine da Python?

Passa le immagini di riferimento come URL nella stessa chiamata. Non esiste un endpoint di modifica separato: aggiungere images trasforma la richiesta in una modifica, e una mask limita il cambiamento a una zona:

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"}],
})

Gli URL devono essere link HTTPS pubblici a file PNG, JPEG o WebP. Puoi inviarne fino a 16. File locali e stringhe base64 vengono rifiutati, quindi carica prima l'immagine sul tuo storage e passa il suo URL.

Cosa deve fare lo script se l'invio va in timeout?

Non inviare di nuovo subito. Un timeout sul POST non dimostra che la richiesta sia stata rifiutata; l'attività potrebbe essere già in esecuzione e addebitata. Controlla le tue attività recenti, oppure ripeti la richiesta solo dopo aver verificato che non sia stata creata alcuna attività. La guida alle attività spiega come distinguere i due casi.

Il polling è diverso: un timeout durante il polling è innocuo. Richiama wait con lo stesso ID.

Domande frequenti

Posso usare invece l'SDK Python di OpenAI?

Non direttamente. Questa API consegna i risultati in modo asincrono tramite un ID attività, mentre la chiamata per immagini dell'SDK si aspetta l'immagine finita nella risposta. Poche righe di requests, come sopra, coprono l'intero flusso.

Come eseguo più prompt?

Invia ogni prompt, salva tutti gli ID attività, poi interrogali. La guida alla generazione in batch mostra una versione che sopravvive ai riavvii senza pagare due volte.

gpt-image-2-official richiede codice diverso?

No. Cambia la stringa model e nient'altro. I due ID accettano gli stessi campi e restituiscono la stessa risposta dell'attività; cambia solo la fatturazione.

Conserva l'ID attività, il resto è routine

Invia, salva l'ID, interroga con una scadenza e scarica ciò che torna indietro. Questo schema è l'intera integrazione. Prova un prompt senza codice nel Playground di GPT Image 2 prima di scriverne lo script.