Come usare gpt-image-2.5-sunburst tramite l'API hiapi: curl, Python ed esempi di richiesta disponibili

Per generare o modificare immagini con gpt-image-2.5-sunburst, invia un task con il prompt a POST /v1/tasks, poi esegui il polling di GET /v1/tasks/<id> (oppure ricevi un callback) finché il task non è completato, e leggi l'URL dell'immagine da data.output[0].url. Questa guida illustra la richiesta minima, l'insieme completo dei parametri e i pattern di produzione necessari prima del go-live (callback, idempotenza, gestione degli errori).

Prerequisiti

Ti serve una chiave API hiapi. Creala dalla console: ogni richiesta viene autenticata con Authorization: Bearer sk-<your-key>. Non esiste un livello gratuito né un modo per chiamarla dal browser senza chiave; tutti gli esempi seguenti presuppongono che tu ne abbia già una.

Esempio minimo funzionante

gpt-image-2.5-sunburst/text-to-image richiede solo prompt dentro input. Il rapporto d'aspetto predefinito è auto, la risoluzione predefinita è 1K.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

Restituisce immediatamente un id del task:

{"code":200,"data":{"taskId":"tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ"},"message":"success"}

Esegui il polling del risultato:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

La versione Python dello stesso ciclo di andata e ritorno:

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url punta a uno storage temporaneo: la risposta include expireAt (secondi Unix). Scarica i byte e rendili persistenti prima di quella scadenza (il tuo storage, S3, R2, ecc.); non trattarlo come un link permanente.

Riferimento completo dei parametri

gpt-image-2.5-sunburst ha due id di modello: gpt-image-2.5-sunburst/text-to-image per la generazione da un prompt e gpt-image-2.5-sunburst/image-to-image per modificare o comporre immagini di riferimento. Entrambi accettano gli stessi campi; la differenza è che image_urls è obbligatorio su image-to-image e non viene usato su text-to-image:

Campo	Tipo	Valore predefinito	Descrizione
prompt	string, 1–8000 caratteri	—	Obbligatorio. Per le modifiche, descrivi cosa deve cambiare e cosa deve restare esattamente identico.
image_urls	array di URL	—	Solo image-to-image, obbligatorio, da 1 a 16 immagini JPEG, PNG o WebP, ciascuna fino a 20 megapixel e non oltre 30 MB. Deve essere un URL scaricabile pubblicamente o un data URI.
aspect_ratio	enum	"auto"	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9.
resolution	enum	"1K"	1K, 2K, 4K. Determina il prezzo.
background	enum	nessuno	transparent, opaque, auto. transparent ha effetto solo con 1K, nel qual caso viene restituito un PNG con canale alpha.

Esempio di modifica: passa una o più immagini di riferimento e descrivi solo le modifiche che vuoi:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

Lo schema è rigoroso (additionalProperties: false): i campi sconosciuti vengono rifiutati, quindi non riutilizzare parametri di altri modelli di immagine (ad esempio size, strength, n).

Pattern di produzione

In un backend reale usa i callback invece del polling. Aggiungi un blocco callback per saltare il ciclo di polling:

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" scatta esattamente una volta quando il task raggiunge uno stato terminale (success o fail). Il tuo endpoint deve restituire rapidamente 2xx ed eseguire il lavoro effettivo in modo asincrono (scaricare l'output, aggiornare il tuo database): hiapi ritenta i callback che non hanno ricevuto una conferma rapida.

Rendi idempotenti i retry. Se una richiesta del client va in timeout, non puoi sapere se il task è stato creato. Invia l'header Idempotency-Key nella richiesta di creazione (massimo 255 byte) e riutilizza la stessa chiave nei retry: con lo stesso account e la stessa chiave viene creato un solo task, e i retry restituiscono il taskId originale. Senza di esso, elaborare due volte lo stesso prompt viene addebitato due volte.

Gestisci gli stati terminali che incontrerai davvero:

• success — leggi data.output[0].url e scarica tempestivamente (rispettando expireAt).
• fail — controlla data.error per capire il motivo del fallimento prima di riprovare; non ritentare ciecamente ogni fallimento, alcuni riguardano il prompt (ad esempio violazioni delle policy) e riprovare identicamente fallirà di nuovo.
• Il polling di un id di task inesistente (refuso, scaduto) restituisce HTTP 404 con {"code":404,"message":"task not found"}.

Il fallimento dell'autenticazione è HTTP 401, non un errore a livello di task:

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

Controlla questo nella gestione degli errori prima di dare per fallito il task: una chiave non valida o revocata non arriva nemmeno alla fase di creazione del task.

Letture correlate

• Pagina del modello GPT Image 2.5 Sunburst — esempi in tempo reale e prezzi attuali.
• GPT Image 2.5: generazione, modifica e migrazione — se stai migrando da una route precedente di Image 2 alla serie 2.5 (Flare o Sunburst), questo articolo illustra le differenze nei parametri.
• Come ristilizzare le immagini con l'AI — se la modalità di modifica di Sunburst è solo una parte della tua pipeline, qui trovi una trattazione più ampia di image-to-image.
• Documentazione sull'autenticazione e Guida rapida per comprendere il ciclo di vita completo della richiesta oltre a questo singolo modello.

Domande frequenti

gpt-image-2.5-sunburst supporta la modifica delle immagini o solo la generazione testo-immagine? Entrambe, tramite due id di modello. Usa gpt-image-2.5-sunburst/image-to-image con image_urls (da 1 a 16 immagini di riferimento) per modificare o comporre, e gpt-image-2.5-sunburst/text-to-image per generare solo dal testo.

Cosa succede se invio un array image_urls vuoto invece di ometterlo? Non farlo. Su image-to-image, image_urls è obbligatorio e richiede almeno un URL. Per la generazione solo testuale usa invece l'id del modello text-to-image.

Quanto costa un'immagine? Dipende da resolution: 1K costa $0.05, 2K $0.08, 4K $0.12, sia per text-to-image che per image-to-image. Durante la promozione per la Giornata del Programmatore (fino al 9 novembre 2026, 00:00 UTC+8), tutti gli scaglioni hanno il 50% di sconto: $0.025, $0.04 e $0.06. Prima di scalare, consulta la pagina del modello per i prezzi in tempo reale.

Posso ottenere dimensioni in pixel fisse invece del rapporto d'aspetto? Sì: oltre a stringhe di rapporto come 16:9, aspect_ratio accetta anche dimensioni letterali come 1024x1024, 1536x1024 o 3840x2160.

Perché il polling del task restituisce 404? O il taskId contiene un refuso, oppure l'endpoint/la regione che stai interrogando non ha quel task. Controlla attentamente l'id salvato dalla risposta di creazione: hiapi non fa scadere silenziosamente i record dei task in nessuna finestra di polling normale.

Posso chiamarlo per provarlo senza chiave API? No. Ogni richiesta a /v1/tasks richiede Authorization: Bearer sk-<key>; non esiste una modalità anonima o solo browser.