API text-to-image GPT Image 2.5 Sunburst: guida pratica con curl e Python

Se vuoi generare immagini tramite l'API hiapi usando gpt-image-2.5-sunburst/text-to-image, questa guida ti accompagna attraverso una richiesta completa e funzionante, usando sia curl che Python — dalla creazione del task al download dell'URL finale dell'immagine. Ogni richiesta/risposta mostrata qui è stata realmente eseguita contro l'API di produzione prima della pubblicazione.

Prerequisiti

• Un account hiapi e una API key (formato sk-...). Puoi ottenerla dalla console hiapi.
• curl, oppure Python 3.8+ se vuoi seguire gli esempi Python.
• Budget per almeno un'immagine di output. gpt-image-2.5-sunburst/text-to-image viene fatturato in base alla risoluzione di output — prima di eseguirlo in produzione consulta i prezzi attuali, poiché le tariffe possono cambiare.

Tutte le richieste usano gli header standard:

Authorization: Bearer sk-your-api-key-here
Content-Type: application/json

Esempio minimo funzionante

I modelli immagine di hiapi funzionano tutti sulla stessa API di task asincrona: crei un task con POST, poi esegui il polling (o ricevi il callback del webhook) finché non raggiunge uno stato terminale, quindi leggi l'URL dell'immagine da output[0].url.

1. Creare il task (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product shot of a ceramic coffee dripper on a marble counter, soft morning light, 35mm lens look",
      "resolution": "2K",
      "aspect_ratio": "4:3",
      "background": "auto"
    }
  }'

Una chiamata riuscita restituisce solo un ID del task — la generazione avviene in modo asincrono:

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

2. Eseguire il polling del risultato

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

Continua a eseguire il polling ogni pochi secondi finché data.status non raggiunge un valore terminale. In caso di successo, la risposta appare così (taskId/URL abbreviati per leggibilità):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01ABCDEF...",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "status": "success",
    "storage": "temp",
    "created": 1789144334,
    "completed": 1789144407,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../output-0.png",
        "artifactId": "146251",
        "expireAt": 1789749206
      }
    ]
  },
  "message": "success"
}

Recupera l'immagine da data.output[0].url. Quell'URL scade (vedi expireAt, un timestamp Unix) — una volta completato il task, scarica subito i byte e archiviati tu stesso, non trattarlo come un link permanente.

3. Esempio Python end-to-end

import time
import requests

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


def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
    payload = {
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {
            "prompt": prompt,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task("A minimalist product shot of a ceramic coffee dripper on a marble counter")
    task = wait_for_task(task_id)
    image_url = task["output"][0]["url"]
    print(f"Done: {image_url}")

    img_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(img_bytes)

Quali campi accetta effettivamente input

Lo schema di gpt-image-2.5-sunburst/text-to-image è piccolo e rigoroso. Accetta solo i seguenti campi — qualsiasi altro campo (quality, size, n, output_format, style, seed) viene rifiutato con un 400:

Campo	Obbligatorio	Valori
prompt	Sì	Qualsiasi stringa
resolution	No (predefinito 1K)	1K, 2K, 4K
aspect_ratio	No	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
background	No	transparent, opaque, auto

Nota che questo è diverso dallo schema del modello nudo gpt-image-2.5-sunburst: quest'ultimo accetta livelli di quality (low/medium/high/xhigh/max/auto) e supporta la modifica image-to-image tramite image_urls. Anche i prezzi sono diversi — prima di fare affidamento su cifre specifiche, verifica su /en/pricing, poiché le tariffe possono cambiare.

Pattern per la produzione

Usare i callback webhook invece del polling

Per qualsiasi scenario oltre a uno script rapido, evita il polling e lascia che hiapi ti richiami al completamento del task. Aggiungi un oggetto callback di primo livello nella stessa richiesta POST /v1/tasks:

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

when: "final" è attualmente l'unico valore supportato — quando il task raggiunge uno stato terminale (success o fail), il tuo endpoint viene chiamato una volta, con un payload di struttura identica a quello ottenuto tramite polling.

Polling vs. callback: il polling è più facile da implementare correttamente in uno script o in un notebook e non richiede un endpoint pubblico, ma spreca richieste e aggiunge latenza (in media il tuo intervallo di polling) prima che tu sappia che è completato. Per integrazioni lato server o qualsiasi scenario ad alta concorrenza, i callback sono più adatti — eviti del tutto il ciclo di polling e ricevi una notifica non appena il task è pronto.

Idempotenza per i retry

L'API dei task accetta una stringa idempotency_key di primo livello, accanto a model/input/callback. Se il tuo client può ritentare il POST dopo un timeout (hai inviato la richiesta ma non hai mai ricevuto una risposta), allega una key stabile in modo da avere un segnale chiaro per il riconoscimento, invece di indovinare se la richiesta originale sia effettivamente arrivata.

Gestire gli errori

Una API key non valida o scaduta restituisce HTTP 401 con un corpo di errore strutturato:

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

Valori input errati (membro enum errato, prompt mancante, campi non supportati) restituiscono HTTP 400 prima della creazione del task — quindi non ti viene addebitato nulla:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Controlla esplicitamente entrambi i casi: ritenta sugli errori di rete/5xx temporanei, ma considera il 400 come un segnale per correggere il corpo della richiesta, non come oggetto di retry ciechi.

Risorse correlate

• Pagina del modello gpt-image-2.5-sunburst — riferimento completo dei parametri e prezzi in tempo reale sia per il modello nudo che per la rotta /text-to-image.
• Prezzi hiapi — tariffe attuali per risoluzione di questo modello e di tutti gli altri.
• Ricette di prompt per GPT Image 2.5 Sunburst — esempi di prompt a cui ispirarti, se cerchi idee prima di iniziare a scrivere lo script.

Domande frequenti

Devo specificare resolution? No — se omesso, il valore predefinito è 1K. Se hai bisogno di output 2K o 4K, impostalo esplicitamente, poiché il prezzo aumenta con la risoluzione.

Posso passare quality come nelle documentazioni di altri modelli GPT Image? Su questa rotta no. gpt-image-2.5-sunburst/text-to-image rifiuta completamente quality — quel parametro esiste solo sull'ID del modello nudo gpt-image-2.5-sunburst, che ha schema e prezzi diversi.

Perché la mia richiesta restituisce un ID task invece dell'immagine direttamente? Ogni modello immagine su hiapi funziona tramite la stessa API di task asincrona (POST /v1/tasks → polling o callback → output[0].url), indipendentemente dalla velocità effettiva del modello sottostante. Costruisci l'integrazione una volta seguendo questo pattern e ogni modello che sostituirai in seguito funzionerà allo stesso modo.

Cosa succede se non scarico l'URL di output in tempo? Scade — il campo expireAt nella risposta del task è il timestamp Unix in cui l'URL temporaneo smette di funzionare. Non appena status è success, scarica e archivia subito i byte da solo.

Posso usare questo modello per la modifica image-to-image? Sulla rotta /text-to-image no. Per la modifica delle immagini usa l'ID del modello nudo gpt-image-2.5-sunburst e passa il campo di input image_urls — consulta la sua pagina del modello per lo schema esatto.

Pronto a provarlo da solo? Ottieni una API key dalla console hiapi e sostituisci il prompt nell'esempio Python qui sopra.