Come usare gpt-image-2.5-flare@pro tramite l'API hiapi: curl, Python e una richiesta eseguibile

gpt-image-2.5-flare@pro è uno dei modelli di immagini disponibili tramite l'API unificata delle attività di hiapi. Questa guida mostra prima una richiesta minima eseguibile con curl e Python, poi illustra i parametri e i pattern necessari per la produzione: callback, idempotenza e gestione degli errori.

Cosa ti serve

• Una chiave API hiapi. Puoi ottenerla dalla console hiapi: ogni chiave inizia con sk-.
• Usa https://api.hiapi.ai come URL di base. Ogni richiesta richiede l'intestazione Authorization: Bearer sk-<your-key>.

La generazione di immagini su hiapi (e su tutti gli altri modelli asincroni: video, TTS, musica) avviene tramite lo stesso endpoint: POST /v1/tasks. Prima crei un'attività, poi puoi eseguire il polling con GET /v1/tasks/:id oppure ricevere un callback al completamento dell'attività. Il riferimento completo è qui: API asincrona unificata.

Esempio minimo eseguibile

curl

Crea l'attività:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

Qui viene restituito un ID attività, non l'immagine: la generazione di immagini è asincrona:

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

Esegui il polling del risultato:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status cambia nell'ordine queued → handling → archiving → success (oppure fail). Quando lo stato è success, l'immagine si trova in data.output[0].url:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt è un timestamp Unix: scarica il file o ripristinalo su un altro host prima che scada, perché dopo la scadenza l'URL smette di funzionare.

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

Installa l'unica dipendenza con pip install requests, esporta HIAPI_API_KEY e poi esegui lo script.

Parametri chiave

gpt-image-2.5-flare offre due route: quella predefinita (usando direttamente l'ID modello gpt-image-2.5-flare) e la route pro (aggiungendo @pro, come in tutti gli esempi sopra). Non esiste un suffisso esplicito @default: passandolo si ottiene MODEL_UNAVAILABLE.

input accetta i seguenti campi:

• prompt (stringa, obbligatorio): l'unico campo obbligatorio.
• aspect_ratio: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto, oppure dimensioni esplicite in pixel come 1536x1024, 2048x2048, 3840x2160.
• quality: low, medium, high, xhigh, max oppure auto.
• output_format: png, jpeg oppure webp.
• background: auto, transparent oppure opaque. Usa transparent insieme a output_format: png o webp per ottenere materiali con sfondo trasparente.

Lo schema è rigoroso: i campi sconosciuti (size, n o qualsiasi campo non elencato) restituiscono 400 INVALID_REQUEST con additional properties '<field>' not allowed, invece di essere ignorati silenziosamente. Se devi modificare un'immagine esistente anziché generarne una da un prompt vuoto, hiapi la offre come ID modello separato: consulta la pagina del modello per le varianti image-to-image.

Pattern per la produzione

Usa i callback invece del polling. Aggiungi un oggetto callback alla richiesta di creazione:

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" è attualmente l'unico valore supportato: quando l'attività raggiunge success o fail, hiapi invia una singola richiesta POST al tuo URL. Il corpo del callback è identico al campo data restituito da GET /v1/tasks/:id.

Invia l'intestazione Idempotency-Key. Se la tua richiesta va in timeout e viene ritentata, la chiave di idempotenza impedisce a hiapi di creare (e fatturare) una seconda attività per la stessa richiesta.

Gestisci esplicitamente gli errori. Una chiave non valida o revocata restituisce HTTP 401:

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

Un input malformato restituisce HTTP 400, con error_code: "INVALID_REQUEST" e un message che indica il campo problematico: controllalo prima di ritentare, perché ritentare con lo stesso corpo della richiesta un 400 fallirà di nuovo.

I prezzi di gpt-image-2.5-flare@pro (fatturati per immagine generata con successo, in base alla risoluzione e al livello di qualità) sono disponibili nella pagina dei prezzi.

Documentazione correlata

• Riferimento API asincrona unificata: ciclo di vita completo delle attività, tutti i tipi di modello
• Creazione di un'attività: struttura di richiesta/risposta di POST /v1/tasks
• Ottenere i dettagli di un'attività: polling con GET /v1/tasks/:id
• Autenticazione: formato delle chiavi API e intestazioni
• Pagina del modello gpt-image-2.5-flare@pro

Domande frequenti

Qual è la differenza tra la route predefinita e @pro? Sono due route separate della stessa famiglia di modelli, selezionate tramite l'ID modello che invii (gpt-image-2.5-flare vs gpt-image-2.5-flare@pro). Prima di scegliere, consulta la pagina del modello e i prezzi per conoscere le attuali differenze in termini di costi e capacità.

Posso generare PNG trasparenti? Sì: imposta "background": "transparent" insieme a "output_format": "png" (oppure "webp").

Perché ricevo additional properties 'size' not allowed? Lo schema è rigoroso. Usa aspect_ratio (che accetta anche dimensioni esplicite in pixel come 1024x1024) invece del campo size.

Quanto è valido l'URL di output? Fino al timestamp Unix expireAt presente nell'oggetto output[0]. Prima di allora scarica o copia il file nel tuo storage: hiapi non continuerà a servire quel file successivamente.

Se ho impostato un callback devo comunque fare polling? No, ma puoi comunque farlo: GET /v1/tasks/:id funziona normalmente indipendentemente dalla presenza di un callback, utile per un controllo manuale se il tuo endpoint di callback ha perso una consegna.

Cosa succede se la mia richiesta contiene sia input_urls sia un prompt errato? La validazione viene eseguita sull'intero corpo della richiesta prima di creare l'attività: qualsiasi campo non valido (incluse le matrici di media malformate) restituisce 400 e non crea l'attività (né addebita alcun costo).