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

gpt-image-2.5-sunburst@pro è la rotta Pro del modello gpt-image-2.5-sunburst su hiapi. Questa guida ti porta da zero a una richiesta funzionante: qual è esattamente l'id del modello, quali campi input accetta esattamente, un esempio curl/Python eseguibile subito e i pattern di produzione che ti servono prima di eseguirlo in modo non presidiato (idempotenza, callback, gestione degli errori).

Cosa devi preparare prima

• Un account hiapi e una API key presa dalla console. Ogni richiesta qui sotto si autentica con Authorization: Bearer sk-<your key>.
• Tutto qui: non serve installare alcun SDK. Ogni modello su hiapi si chiama attraverso lo stesso endpoint di task asincrono, quindi se hai già chiamato qualsiasi altro modello hiapi, la struttura di questa richiesta ti sarà familiare.

L'unica cosa specifica di questo modello: @pro è un suffisso di rotta, non un soprannome.hiapi espone più di una modalità di chiamata per alcuni modelli, e gpt-image-2.5-sunburst è uno di questi: l'id del modello normale e l'id con suffisso @pro accettano campi input diversi e vengono fatturati su fasce di prezzo diverse. Questa guida riguarda specificamente gpt-image-2.5-sunburst@pro; usando l'id nudo gpt-image-2.5-sunburst ottieni una modalità diversa con uno schema diverso (vedi FAQ).

Esempio minimo eseguibile

Ogni modello di generazione di hiapi — immagini, video o audio — si chiama attraverso lo stesso endpoint unificato: POST /v1/tasks. Invii model e input, ricevi subito un taskId e la generazione avviene in modo asincrono.

Per gpt-image-2.5-sunburst@pro, input accetta:

Campo	Tipo	Obbligatorio	Descrizione
prompt	string	Sì	Da 1 a 32.000 caratteri
image_urls	string[]	No	Da 1 a 16 URL pubblici JPEG/PNG/WebP; includilo per fare image-to-image anziché text-to-image (SVG non supportato)
aspect_ratio	enum	No	Ad esempio 1:1, 16:9, 9:16, oppure dimensioni esplicite come 1536x1024; predefinito 1:1
quality	enum	No	low / medium / high / xhigh / max / auto; predefinito medium — prima di alzarlo leggi le note di produzione qui sotto
background	enum	No	transparent, opaque o auto; predefinito auto
output_format	enum	No	png, jpeg o webp; predefinito webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper on a light wood table, soft studio lighting",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

Restituisce immediatamente un taskId:

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

Poi esegui il polling per ottenere il risultato:

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Quando data.status diventa success, l'immagine si trova in data.output[0].url.Scaricala subito: quell'URL ha un expireAt e non è adatto come riferimento permanente esterno.

Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "A minimalist product photo of a ceramic pour-over coffee dripper "
                      "on a light wood table, soft studio lighting",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

Modalità di produzione

Polling e callback. Il ciclo qui sopra va bene per script e traffico ridotto. Per qualsiasi scenario lato server, preferisci le callback al polling: aggiungi un oggetto callback nella stessa richiesta —

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url deve essere HTTPS, e when: "final" (l'unico valore supportato al momento) ti notifica una volta in caso sia di successo sia di fallimento — nessun ciclo di polling, nessuna richiesta sprecata. hiapi può consegnare la callback più volte, quindi deduplica dal tuo lato in base a taskId.

Idempotenza. Aggiungi l'header Idempotency-Key su POST /v1/tasks (una stringa qualsiasi fino a 255 byte, ad esempio un id ordine). Se un timeout di rete fa sì che il tuo client ritenti lo stesso invio, la piattaforma restituisce il taskId originale (con l'header di risposta Idempotent-Replay: true) invece di creare — e fatturare — un secondo task. La chiave è limitata al tuo account e scade dopo 24 ore; riutilizzarla con un corpo di richiesta diverso restituisce 422 IDEMPOTENCY_KEY_MISMATCH invece di creare silenziosamente un nuovo task, quindi la mancata corrispondenza è un segnale che ti invita a controllare la logica di retry, non a riprovare alla cieca.

Errori di autenticazione. Una API key malformata o errata fallisce rapidamente, restituendo 401 con codice di errore permission_denied, e prima di qualsiasi creazione di task:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Se vedi questo, la correzione è quasi sempre la chiave stessa (variabile d'ambiente sbagliata, chiave scaduta, prefisso sk- mancante) — non il corpo della richiesta. Finché la chiave non è corretta, trattalo come non ritentabile.

Sul quality.quality è medium per impostazione predefinita, un valore ragionevole per una prima release — alzarlo aumenta sia i costi sia i tempi di generazione, quindi passa a high/xhigh/max solo dopo aver verificato nei tuoi test che un dato prompt riesca ancora in modo affidabile a quel livello.

Pagine correlate

• Pagina del modello gpt-image-2.5-sunburst — capacità della famiglia di modelli, output di esempio e tutte le modalità disponibili.
• Documentazione dell'API asincrona unificata — il contratto completo di /v1/tasks condiviso da tutti i modelli di generazione hiapi (idempotenza, callback, codici di stato).
• Documentazione sull'autenticazione — come creare e gestire le API key.
• Guida all'API gpt-image-2.5-sunburst — se vuoi la modalità base (non @pro), questa guida descrive in dettaglio il suo schema separato basato su resolution.
• Prezzi — il costo attuale per immagine per fascia di quality.

FAQ

gpt-image-2.5-sunburst@pro e gpt-image-2.5-sunburst sono modelli diversi? Stessa famiglia di modelli, rotta diversa. L'id nudo gpt-image-2.5-sunburst (e la sua modalità /text-to-image) accetta un campo resolution (1K/2K/4K) e non ha campi quality o image_urls. @pro lo sostituisce con le fasce di quality e aggiunge image_urls opzionale, quindi usa questa rotta quando vuoi controllare la fascia di qualità o fare image-to-image nella stessa chiamata.

Mi servono immagini di riferimento? No. Per il text-to-image ometti del tutto image_urls. Includendo da 1 a 16 URL di immagini pubbliche passi invece a condizionare l'output con immagini di riferimento.

Posso usare questo modello senza API key? No — ogni richiesta richiede un header Authorization: Bearer valido con una vera API key hiapi del tuo account. Non esistono modalità non autenticate o senza chiave.

Quanto costa? Il prezzo varia in base alla fascia di quality e viene mantenuto aggiornato nella pagina dei prezzi, invece di essere ripetuto qui — consultala prima di stimare i costi su larga scala.

Cosa faccio se la mia callback non arriva mai? La consegna delle callback non è garantita in tempo reale e hiapi può ritentare la consegna (quindi deduplica in base a taskId). Se ti serve un limite rigido, mantieni un polling di fallback su GET /v1/tasks/:id dopo il timeout, invece di aspettare la callback all'infinito.

Perché ricevo lo stato fail invece di un errore all'invio? L'invio (che restituisce 200/taskId) significa solo che la richiesta è stata accettata — la generazione stessa può comunque fallire in modo asincrono. Controlla data.status dopo il polling o tramite callback, e controlla data.error per il motivo prima di reinviare.