Integrazione API GPT Image 2.5: generazione, modifica e migrazione da Image 2

Per integrare GPT Image 2.5 su HiAPI, scegli prima gpt-image-2.5-flare o gpt-image-2.5-sunburst, poi invia il task tramite POST /v1/tasks. Entrambi i modelli supportano generazione e modifica; la presenza o meno di image_urls determina se la richiesta include immagini di riferimento.

Quando si migra da Image 2, occorre modificare sia il nome del modello sia i parametri di input. La versione precedente usa convenzioni diverse per resolution, size, i campi delle immagini di riferimento e le impostazioni di route: sostituire solo la stringa del modello rischia di lasciare parametri non applicabili.

Il codice seguente è scritto in base alla documentazione online di HiAPI al 9 settembre 2026, per illustrare il flusso di richiesta ed elaborazione asincrona; l'output effettivo e i costi fanno fede ai record del task. Per gli aggiornamenti dei parametri fanno fede la documentazione di Flare e la documentazione di Sunburst.

Un unico ID modello per generazione e modifica

Flare e Sunburst hanno gli stessi campi di richiesta su HiAPI. Dopo aver scelto un modello, per la generazione da solo testo si omette image_urls; per la modifica si aggiungono da 1 a 16 immagini di riferimento e nel prompt si specifica cosa modificare e cosa conservare. Non inviare un array vuoto per la generazione da solo testo e non è necessario aggiungere autonomamente i suffissi /edit o /text-to-image. Ogni task produce un'immagine.

Se disponi già di un flusso di lavoro stabile per le immagini, puoi iniziare migrando un tipo di task, mantenendo gli input e i criteri di accettazione originali. Per l'posizionamento dei due modelli, consulta prima la differenza tra Image 2 e 2.5; questo articolo si concentra su come implementare la richiesta.

Inviare una richiesta di generazione

L'esempio seguente genera un'immagine quadrata di una tazza come prodotto. Salva il JSON come request.json. quality è impostato esplicitamente su medium per facilitare la riproduzione dei parametri; aspect_ratio è impostato sulla dimensione in pixel 1024x1024 elencata nella documentazione.

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

La API Key va inserita nella variabile d'ambiente lato server HIAPI_API_KEY. Il comando seguente legge il file, lo invia e salva la risposta di creazione del task. HIAPI_REQUEST_ID è generato dalla tua applicazione per questa singola richiesta logica; riutilizzalo quando ripeti la stessa richiesta per problemi di rete, e usa un nuovo valore quando modifichi gli input o crei un'altra immagine.

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

Dopo la creazione riuscita, leggi l'ID del task da data.taskId in created.json. A questo punto l'immagine è ancora in fase di generazione asincrona. Idempotency-Key serve a evitare che la stessa richiesta logica crei più task per invii ripetuti; per le convenzioni complete vedi la documentazione sulla creazione dei task. Non considerare l'invio riuscito come immagine già completata.

Modificare un'immagine con la stessa interfaccia

Segue una richiesta di modifica Sunburst separata. Sostituisci l'indirizzo segnaposto in image_urls con l'URL reale di un'immagine di riferimento accessibile dal servizio, salva come request.json e invia con un nuovo ID richiesta. Gli indirizzi example.com servono solo a illustrare la struttura dei campi e non possono essere usati direttamente per la generazione.

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

Con più immagini di riferimento, descrivi l'uso nell'ordine dell'array, ad esempio la prima fornisce il prodotto e la seconda lo sfondo. Per modifiche consecutive, usa l'output salvato nel passaggio precedente come immagine di riferimento della richiesta successiva; ogni volta si tratta comunque di un nuovo task e occorre specificare chiaramente i nuovi requisiti di modifica. Non dare per scontato che l'interfaccia conservi automaticamente la conversazione o l'immagine del turno precedente.

Per lo sfondo trasparente imposta background su transparent e scegli PNG o WebP. JPEG non supporta il canale di trasparenza. Anche dopo l'output del modello è necessario controllare bordi e soggetto; l'impostazione dei campi non sostituisce la verifica dell'immagine.

Interrogare lo stato, poi salvare il file

GET /v1/tasks/:id restituisce i dettagli del task. queued, handling, archiving sono tutti stati non finali; solo success indica che l'output è disponibile, mentre fail fornisce le informazioni di errore tramite data.error. Il code: 200 esterno indica solo che la query è riuscita: occorre continuare a valutare data.status. Documentazione dettagli task

L'esempio Python seguente usa requests, legge il created.json appena creato, attende prima 3 secondi e poi interroga ogni 4 secondi. Salva il JSON dei dettagli e la prima immagine. I 10 minuti sono il limite di attesa locale dell'esempio: non rappresentano uno SLA del servizio e non annullano il task lato server. Dopo il timeout conserva il taskId e continua a interrogare lo stesso task più tardi.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

Gli output temporanei devono essere scaricati o trasferiti prima di output[].expireAt. Per i servizi in produzione è possibile configurare callback a livello superiore della richiesta per ricevere la notifica di stato finale, mantenendo il polling come fallback; i campi di callback non vanno inseriti in input. La verifica della firma del callback e la gestione delle notifiche duplicate vanno implementate secondo la API asincrona unificata. L'esempio non include code di business, servizi di callback o una strategia completa di retry di rete.

Migrare da Image 2, verificando gli input uno per uno

La precedente Image 2 ha route diverse; durante la migrazione, verifica prima quale stai usando. Quella che segue è la differenza dei parametri tra le documentazioni HiAPI, non si applica al trasferimento diretto delle richieste SDK di altri provider.

Flusso di lavoro precedente	Modifica per Image 2.5
Generazione e modifica usano ID modello Image 2 diversi	Passa all'ID completo di Flare o Sunburst; distingui in base alla presenza di image_urls
La modifica Standard usa input_urls	Passa a image_urls; la precedente modifica ext usava già questo campo
Standard / ext usano resolution	Riseleziona in base alla dimensione target l'enumerazione di proporzioni o pixel in aspect_ratio, non mantenere resolution
La generazione Beta usa size	Passa all'enumerazione in pixel di aspect_ratio supportata dalla documentazione, non copiare dimensioni arbitrarie
route: "beta" / "ext" esplicito, o nome del modello con suffisso di route	Ricostruisci la richiesta secondo la documentazione del modello 2.5, non riutilizzare le vecchie route
Proporzioni come 4:5 supportate dalla versione precedente	Verifica voce per voce; l'enumerazione attuale di 2.5 non include 4:5, non cambiarla silenziosamente con un'altra proporzione
Affidamento alla qualità, dimensione o formato di output predefiniti	Specifica esplicitamente e ricontrolla output, costi e gestione dei file a valle

Le opzioni di proporzione attuali di 2.5 sono 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 e auto. Inoltre, aspect_ratio accetta le 10 dimensioni in pixel elencate nella documentazione. Se serve una dimensione fissa, scegli un valore dell'enumerazione; non dedurre dal formato della stringa che qualsiasi widthxheight sia disponibile. In particolare auto, secondo la nuova documentazione, è descritto come scelta della composizione adeguata da parte del modello, e non va ereditato direttamente il presupposto della vecchia route di modifica di "seguire l'immagine di input".

Le opzioni di qualità sono low, medium, high, xhigh, max, auto, con valore predefinito medium. I livelli di qualità con lo stesso nome non garantiscono costi o resa visiva identici ai modelli precedenti. Per il protocollo precedente completo consulta la documentazione Generazione Image 2 e Modifica Image 2.

Errori e budget, nella stessa catena di accettazione

Un 400 all'invio richiede di controllare nome del modello, campi ed enumerazioni; un 402 richiede di controllare il saldo; un 415 richiede di controllare Content-Type. Se dopo la creazione del task compare fail, salva data.error per la diagnosi e non reinviare lo stesso input non valido. Un 503 può essere ritentato con backoff dopo un po'; se per un'interruzione di rete del POST non è possibile determinare se il task è stato creato, usa la chiave di idempotenza originale per evitare task duplicati. Spiegazione degli errori di creazione task

La verifica dei costi parte dalla pagina dei prezzi attuali di HiAPI e dalle pagine dei singoli modelli. La verifica di migrazione deve registrare modello completo, dimensioni, qualità, numero di immagini di riferimento, richiesta, output e fattura effettiva; non riutilizzare il prezzo unitario della vecchia Image 2 e non trattare i prezzi di partenza di altre piattaforme come quotazione di HiAPI. Le immagini di esempio sul sito web aiutano a valutare i risultati; tempi API e fattura richiedono ciascuno i propri record effettivi.

Dopo aver integrato, salvato e verificato un task di generazione e uno di modifica, estendi al flusso batch. Puoi consultare l'ingresso attuale dalla pagina del modello Flare o dalla pagina del modello Sunburst, quindi mantenere i parametri secondo la rispettiva Docs.