GPT Image 2.5

GPT Image 2.5 accetta un prompt testuale e, facoltativamente, immagini di riferimento. Invia una volta, conserva l'identificativo dell'attività restituito e interroga quell'attività per ottenere le immagini finite. È disponibile come due modelli che leggono gli stessi parametri: Flare per il lavoro quotidiano e Sunburst quando la precisione delle modifiche conta di più.

ID modello

Tutti e quattro gli ID accettano gli stessi parametri. I canali differiscono nella fatturazione; consulta la pagina del modello per i prezzi attuali.

Esempio rapido

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

Lo stesso endpoint gestisce generazione, modifiche con riferimento e modifiche con maschera. La risposta contiene un identificativo di attività, non l'immagine finita. Tieni le chiavi API nel codice lato server.

Parametri

Regole sulle dimensioni

Le scelte più comuni sono 1024x1024, 1536x1024 e 1024x1536. Le dimensioni personalizzate devono rispettare tutte le regole:

• Larghezza e altezza sono multipli di 16.
• Nessun lato supera i 3840 pixel.
• Il rapporto d'aspetto è compreso tra 1:3 e 3:1.
• L'area totale è compresa tra 655.360 e 8.294.400 pixel, estremi inclusi.

auto lascia le dimensioni di uscita al modello. Non inviare rapporti d'aspetto come 16:9 in size.

Il Playground offre i controlli Auto, Proporzione e Personalizzato. La modalità Proporzione combina un rapporto d'aspetto con un preset di budget di pixel a 1K, 2K o 4K, poi invia solo il size risultante. Sono preset dell'interfaccia, non parametri API separati: non inviare resolution né aspect_ratio. Ad esempio 16:9 + 4K invia size: "3840x2160"; 9:16 + 4K invia "2160x3840"; 1:1 + 2K invia "2048x2048". Arrotondamenti e limite di lato possono ridurre il numero di pixel di un livello selezionato. Le dimensioni esatte vengono mostrate prima dell'invio.

OpenAI definisce sperimentali le risoluzioni superiori a 2560×1440. Entro i limiti sopra indicati vengono accettate; una risoluzione più alta non garantisce però un dettaglio migliore.

Livelli di qualità

xhigh e max sono novità di GPT Image 2.5; GPT Image 2 si ferma a high. I livelli più alti richiedono più tempo di rendering e, sugli ID fatturati a token, consumano più token di output. Misurato a 1024x1024, un rendering ha dichiarato 196, 439, 1.756, 3.122 e 7.024 token di output per low, medium, high, xhigh e max. Sono campioni osservati, non garanzie: l'utilizzo dipende anche da dimensione e contenuto.

Usa low per le bozze e confronta i risultati prima di scegliere un livello superiore. auto lascia scegliere al modello; non garantisce un livello o un costo specifico.

Sfondi trasparenti

La trasparenza è supportata per GPT Image 2.5. Per uno sfondo trasparente imposta background: "transparent" e usa PNG. JPEG non supporta la trasparenza. La compressione si applica solo a JPEG.

user è disponibile per le integrazioni API ma non viene mostrato né compilato automaticamente nel Playground.

Le impostazioni scalari facoltative (n, size, quality, background, output_format, output_compression, moderation) accettano null come omissione. I campi sconosciuti vengono rifiutati. input_fidelity non è un parametro di GPT Image 2.5. style e response_format appartengono ad altri modelli di immagini e qui non sono accettati.

Modalità

Non esiste un parametro di modalità separato né un endpoint di modifica da scegliere.

Modificare immagini di riferimento

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
  }'

Sostituisci entrambi gli URL di esempio con immagini tue accessibili. Ometti mask per una modifica con riferimento senza area selezionata.

Input multimediali

Questa API accetta solo riferimenti tramite URL. Non sono accettati identificativi OpenAI Files, data URL in base64 e caricamenti multipart. Il Playground carica i file selezionati nello storage prima di inviarne gli URL.

Le immagini di riferimento devono essere URL HTTP(S) pubblici che puntano a file PNG, JPEG o WebP di meno di 50 MB ciascuno. Una maschera deve essere un PNG di meno di 4 MB, con le stesse dimensioni della prima immagine di riferimento; la sua area trasparente indica cosa modificare. La maschera guida il modello e non garantisce bordi esatti al pixel. Con più riferimenti, la maschera si applica alla prima immagine. I media indicati tramite URL vengono convalidati durante l'elaborazione; media non validi o non raggiungibili possono far fallire l'attività.

Il Playground carica i file selezionati e ne invia gli URL. Le richieste API usano oggetti URL in JSON: non inviare byte di file, base64, URL data:, URL blob: o dati di form multipart.

Fattori di costo

Consulta la sezione prezzi del modello per le tariffe correnti. Gli ID Standard addebitano un prezzo fisso per immagine consegnata, indipendentemente da qualità, dimensione e prompt. Con gli ID Official il costo finale dipende dal consumo in input e output: qualità, dimensioni di output, immagini di riferimento, lunghezza del prompt e numero di immagini possono influire.

La stima del Playground si basa su un campione misurato e sulle tariffe correnti; non è un preventivo garantito. Gli addebiti definitivi sono nello storico di utilizzo del tuo account. Le attività fallite non vengono addebitate.

Schema di output

L'invio restituisce un riferimento all'attività:

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

Interrogare l'attività

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

Interroga a intervalli moderati, ad esempio ogni tre secondi, finché status non diventa completed o failed. Un timeout di rete durante il polling non significa che la generazione sia fallita: conserva l'identificativo dell'attività e riprendi il controllo. Non creare un'altra attività per verificare l'avanzamento.

Esempio di polling completo

Esegui questo dopo l'esempio di invio in Python qui sopra. Usa il task_id restituito e attende fino a dieci minuti. Raggiungere questa scadenza locale interrompe solo il polling; conserva l'identificativo e riprendi a interrogare la stessa 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}.")

Attività completata

Un'attività completata restituisce gli URL delle immagini ospitate e l'utilizzo:

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

Questa API consegna i risultati in modo asincrono tramite attività. Non sostituisce un SDK Images sincrono; stream e partial_images non sono supportati.

Errori

Le richieste rifiutate prima della creazione di un'attività restituiscono un errore HTTP con un oggetto error. Un'attività che fallisce dopo l'accettazione restituisce HTTP 200 all'interrogazione, con status: "failed" e un oggetto error.

Vedi il catalogo errori comune per codici, stati HTTP e indicazioni sui tentativi. Tutte le API dei modelli usano la stessa struttura di errore.

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

Se è l'invio stesso ad andare in timeout, controlla lo storico delle attività prima di inviare di nuovo: la prima richiesta potrebbe essere già stata accettata.

Suggerimenti

• Descrivi materiali, composizione e illuminazione nel prompt.
• Per una modifica, indica sia il cambiamento sia ciò che deve restare invariato.
• Usa una maschera quando deve cambiare solo una zona selezionata.
• Salva le immagini restituite nel tuo storage se ti serve una copia duratura.

Correlati

• Playground e prezzi di GPT Image 2.5
• Scarica l'OpenAPI
• Markdown copiabile