Come usare imagen-4.0 tramite l'API HiAPI: curl, Python ed esempi di richiesta funzionanti

Le capacità di imagen-4.0 che HiAPI ti mette a disposizione

imagen-4.0 è un modello di generazione di immagini da testo: invii un prompt in linguaggio naturale e ricevi un'immagine generata. Per chi integra, ciò che conta davvero non è l'architettura del modello, ma il contratto di interfaccia che lo circonda. Tramite HiAPI, quel contratto è un endpoint HTTP — accetta JSON e autentica con una chiave bearer — esattamente lo stesso schema che già conosci dalle chiamate di chat completion e di embedding.

I vantaggi concreti di usare HiAPI invece di collegarti direttamente al modello:

• Schema di autenticazione unificato. La stessa chiave API vale per tutti i modelli della piattaforma, quindi non devi passare da una credenziale all'altra di più fornitori.
• Formato di richiesta unificato. Un corpo JSON con l'identificatore del modello e il prompt. Nessuna struttura di richiesta specifica di un SDK da imparare.
• Risposta sincrona. imagen-4.0 restituisce il risultato nella stessa risposta HTTP, quindi negli scenari di base non serve costruire cicli di polling o webhook.

Questa guida ti accompagna da zero alla costruzione di una richiesta funzionante sia in curl sia in Python, poi spiega come leggere la risposta e cosa preparare prima di andare in produzione.

Ottenere la chiave API e configurare l'autenticazione

Ogni chiamata a imagen-4.0 su HiAPI si autentica con un bearer token. Crei una chiave API nel tuo account HiAPI, e da quel momento quella chiave è l'unica credenziale necessaria alla richiesta — nessun ID progetto separato, nessun header firmato.

Il principio che evita la maggior parte degli incidenti: la chiave va in una variabile d'ambiente, mai nel codice sorgente. Una chiave incollata in uno script e inviata a un repository è una chiave che dovrai ruotare.

Configurazione locale

Esporta la chiave nella sessione della shell:

export HIAPI_API_KEY="your-key-here"

Se vuoi che la variabile sia persistente, aggiungi questa riga al file di configurazione della shell; oppure usa un file .env, inseriscilo in .gitignore e caricalo all'avvio dell'applicazione.

Ambienti distribuiti

In CI e in produzione, imposta HIAPI_API_KEY tramite il gestore di segreti della piattaforma — iniettando la variabile d'ambiente a runtime, non inserendo il file nell'immagine. Così il codice applicativo è identico tra locale e ambiente distribuito, cambia solo l'origine della variabile.

Header

Ogni richiesta porta con sé:

Authorization: Bearer $HIAPI_API_KEY

Se vedi un 401, la prima cosa da controllare è che l'header venga effettivamente inviato e che la variabile si risolva in un valore non vuoto. Una shell in cui la variabile non è mai stata esportata invierà comunque Bearer , seguito da nulla.

Capire la struttura della richiesta prima di inviarla

Il corpo di una richiesta imagen-4.0 è così piccolo da poterlo tenere a mente, ed è proprio questo il punto: una volta capito lo schema, puoi costruire la richiesta in qualsiasi linguaggio senza dover tradurre uno snippet copiato e incollato.

Il minimo da inviare:

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

Due campi fanno il lavoro principale:

• model indica quale modello elabora la richiesta. È una stringa, lo stesso identificatore che la piattaforma usa ovunque elenchi imagen-4.0. Se lo sbagli ottieni una risposta di errore, non un fallback silenzioso.
• prompt è la descrizione dell'immagine che vuoi. Scrivilo come descriveresti la scena a una persona: soggetto, ambientazione, stile, illuminazione. Prompt specifici producono risultati più prevedibili rispetto a prompt di una sola parola.

La richiesta viene inviata con POST, Content-Type: application/json, all'endpoint di generazione immagini della piattaforma. Il modello potrebbe avere parametri opzionali aggiuntivi, ma il corpo a due campi qui sopra è una richiesta completa e valida — parti da qui e aggiungi opzioni solo quando servono.

Poiché il corpo è puro JSON, curl, Python, Node e qualsiasi strumento dotato di client HTTP sono cittadini di prima classe. Le due sezioni successive mostrano lo stesso request scritto in due modi.

Richiesta curl funzionante

Parti dal terminale, dove puoi vedere la risposta grezza senza interferenze di parsing.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

Riga per riga:

• -sS silenzia la barra di progresso ma mostra comunque gli errori, così l'output resta leggibile senza nascondere i fallimenti.
• -X POST imposta il metodo della richiesta. La generazione di immagini crea contenuto, quindi POST.
• L'URL è l'endpoint di generazione immagini della piattaforma, composto dal tuo base URL più il percorso. Tieni il base URL in una variabile, così lo stesso comando funziona in ambienti diversi.
• Il primo header porta la tua chiave bearer, letta dalla variabile d'ambiente esportata prima.
• Content-Type: application/json dice al server come interpretare il corpo della richiesta.
• -d fornisce il corpo JSON. Gli apici singoli impediscono alla shell di interpretare parentesi graffe e virgolette; il JSON all'interno è letterale.

Se vuoi ispezionare l'output, passalo a un formattatore JSON:

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

Se la risposta contiene un riferimento all'immagine, la richiesta è andata a buon fine. La sezione successiva la trasforma in codice applicativo.

La stessa richiesta in Python

La chiamata curl si traduce direttamente. L'unica vera scelta è il client HTTP; la libreria standard urllib funziona ovunque, ma requests produce codice più breve ed è la libreria da cui la maggior parte dei codebase dipende già.

Funzione di supporto riutilizzabile

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

Tre cose da notare:

• os.environ["HIAPI_API_KEY"] solleva immediatamente un KeyError se la variabile manca, fallendo in modo rapido e rumoroso invece di inviare un token vuoto.
• json= serializza automaticamente il dizionario e imposta il content type, quindi il comportamento della richiesta è identico a quello della versione curl.
• timeout=120 limita la durata della chiamata. La generazione di immagini richiede più tempo di un completamento testuale, quindi si usa un timeout generoso invece di nessun timeout per default.

La funzione accetta il prompt come argomento e restituisce il JSON parsato, il che significa che il resto del tuo codice non deve toccare i dettagli HTTP. Testala nella REPL prima di collegarla a qualsiasi cosa.

Leggere la risposta sincrona e gestire gli errori

imagen-4.0 risponde in modo sincrono: l'immagine generata viene restituita nel corpo della stessa risposta HTTP. Negli scenari di base non c'è alcun job ID da interrogare né ciclo di polling da scrivere — tratta la chiamata come qualsiasi altra interazione richiesta-risposta.

Cosa viene restituito

La risposta di successo è un oggetto JSON. In Python la parsi con response.json(), oppure passi l'output di curl a un formattatore JSON, poi individui i dati dell'immagine nella struttura restituita — di solito un URL o un payload immagine codificato, insieme a metadati sulla generazione. Leggi una volta i nomi esatti dei campi da una risposta reale, poi scrivi il codice di conseguenza.

Problemi da prevenire

Avvolgi la chiamata e controlla lo stato prima di parsare:

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

Modalità di fallimento da gestire esplicitamente:

• 401 — chiave mancante o non valida. Correggi la variabile d'ambiente, non il codice.
• 4xx generici — corpo della richiesta malformato, identificatore del modello errato o prompt rifiutato. Il corpo della risposta di solito indica quale dei tre. Registralo nei log.
• 5xx — guasto lato server. Questi valgono un nuovo tentativo con backoff.
• Timeout — trattalo come esito sconosciuto, non come successo; non dare per scontato che l'immagine sia stata generata.

In caso di fallimento registra sempre il codice di stato e il corpo della risposta troncato. Fare debug senza queste informazioni è tirare a indovinare.

Dalla prima richiesta alla produzione

La richiesta funziona già. Prima di scalare, controlla punto per punto:

• Configurazione. Sia il base URL sia la chiave API provengono dall'ambiente. Nessun valore letterale nel codice sorgente, nessuna chiave nell'immagine.
• Timeout. Ogni chiamata di generazione immagini ha un timeout. Senza, una richiesta bloccata potrebbe occupare indefinitamente un processo worker.
• Retry. Riprova solo per 5xx e timeout, con backoff esponenziale e un limite massimo. Non riprovare mai i 401 o i 4xx con corpo malformato — fallirebbero esattamente allo stesso modo.
• Logging. Registra per ogni chiamata modello, lunghezza del prompt, codice di stato e latenza. Non registrare le chiavi, e se i prompt possono contenere dati utente non registrare il prompt completo.
• Consapevolezza dei costi. La generazione di immagini è fatturata sull'output prodotto, quindi monitora quante immagini vengono richieste per utente o per job e imposta limiti a livello applicativo. Per le tariffe attuali consulta il pannello prezzi della piattaforma, non questa guida.
• Concorrenza. Le chiamate di generazione immagini sono più lente di quelle testuali. Dimensiona il pool di worker in base a questo, non dando per scontata la latenza di una chat-completion.

Una volta sistemati questi punti, la stessa funzione di supporto generate_image funziona senza modifiche per job batch, funzionalità rivolte agli utenti e strumenti interni. Per maggiori dettagli sull'integrazione, consulta la documentazione della piattaforma.