Come usare Nano-Banana-2-Lite tramite l'API HiAPI: curl, Python e una richiesta funzionante

Cos'è Nano-Banana-2-Lite e quando usarlo

Nano-Banana-2-Lite è il livello a costi ultra-bassi della famiglia Nano-Banana su HiAPI. È pensato per scenari di generazione di immagini ad alta concorrenza e sensibili ai costi, dove conta di più un costo prevedibile e un'iterazione rapida rispetto alla massima fedeltà. Se stai prototipando una funzionalità, generando in batch miniature o varianti, oppure eseguendo attività in background che tollerano un modello più leggero, questo livello è il punto di partenza giusto.

Usalo quando l'output è solo un tassello di una pipeline più grande: bozze visive, segnaposto, esperimenti in batch o test A/B che richiedono molte candidate a basso costo. Per i materiali visivi definitivi o per scenari che richiedono il massimo dettaglio, passa a un livello superiore. L'interfaccia API resta invariata, quindi puoi cambiare modello senza riscrivere l'integrazione.

Prerequisiti e struttura della richiesta

Prima di chiamare Nano-Banana-2-Lite, assicurati di avere:

• Un account HiAPI e una chiave API. Conservala in una variabile d'ambiente, ad esempio HIAPI_API_KEY; non inserirla mai nel controllo del codice sorgente.
• Un terminale con curl per il primo test, più Python 3.8+ e la libreria requests per la versione script.
• Un prompt che descriva l'immagine che desideri. Inizia in modo semplice; in seguito potrai aggiungere input di riferimento.

Ogni richiesta a HiAPI segue la stessa struttura: un POST con corpo JSON verso l'endpoint del modello. Il corpo della richiesta contiene il nome del modello, il prompt e gli eventuali parametri opzionali. Poiché la generazione è asincrona, la chiamata di invio restituisce un identificatore del job, che poi interroghi a intervalli. La risposta è in JSON; gli errori includono un codice di stato e un messaggio che puoi registrare.

Il tuo payload deve contenere almeno model impostato su nano-banana-2-lite e un prompt. I campi opzionali come reference_images e le impostazioni di output sono descritti nelle sezioni successive.

Una richiesta curl funzionante

Ecco un esempio completo, pronto da copiare e richiamare, per inviare un job di base. Sostituisci il prompt segnaposto con il tuo contenuto.

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

La risposta contiene l'id del job e un campo status. I job appena inviati restituiscono in genere queued o processing. Salva l'id; lo userai nel passaggio di polling. Se ricevi un 401, verifica che HIAPI_API_KEY sia esportata nella tua shell. Se ricevi un 422, controlla il messaggio di errore per individuare il campo problematico.

Inviare la stessa richiesta con Python

Porta la chiamata curl in Python per inserirla in uno script o in un servizio. Questo esempio usa requests e legge la chiave dalla variabile d'ambiente.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

Mantieni il corpo della richiesta in un dizionario, così puoi estenderlo con campi opzionali senza riscrivere la chiamata. Per il passaggio di invio, un timeout di 30 secondi è ragionevole, poiché il lavoro pesante avviene in modo asincrono.

Aggiungere input di riferimento opzionali

Gli input di riferimento ti consentono di guidare la generazione con un contesto visivo. Su HiAPI, li aggiungi come array reference_images nello stesso corpo JSON. Ogni voce è un URL accessibile pubblicamente o un data URI base64. Usa le immagini di riferimento quando vuoi preservare la composizione, allinearti a uno stile o mantenere coerente un'immagine di prodotto tra più varianti.

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

Includi le immagini di riferimento solo quando forniscono un segnale utile. Ogni riferimento è un dato aggiuntivo da trasmettere e può diluire un prompt semplice. Per attività dirette di text-to-image, ometti del tutto il campo. Quando usi i riferimenti, mantienili pertinenti e poco numerosi; una o due immagini ben scelte di solito battono un gruppo grande.

Eseguire il polling dei risultati asincroni

La generazione di immagini è asincrona: invii il job, poi interroghi l'endpoint del job fino a quando lo stato diventa terminale. Lo schema è identico sia in curl sia in Python.

Con curl, controlla il job tramite il suo id:

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

In Python, avvolgi il polling in un ciclo con un ritardo, per non martellare l'API:

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

Inizia con un intervallo breve e, se interroghi molti job, applica un backoff progressivo. Imposta sempre un numero massimo di tentativi, così un job bloccato non blocca per sempre il tuo worker. Considera failed come stato terminale e registra il messaggio di errore.

Scaricare e verificare l'output

Quando un job riesce, la risposta contiene uno o più URL di output. Scarica il file e salvalo localmente, poi verifica cosa hai ottenuto.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

Esegui controlli di base sul contenuto scaricato: verifica che il content type sia un'immagine, controlla che la dimensione del file sia diversa da zero e ragionevole, e aprilo una volta per confermare che corrisponda al tuo prompt. Registra l'id del job insieme al nome del file locale, così puoi risalire da qualsiasi materiale alla sua richiesta.

Checklist di costi e guasti prima della messa in produzione

Nano-Banana-2-Lite ha un prezzo nel livello a costi ultra-bassi; la fatturazione segue la metrica standard di generazione di immagini della piattaforma. Consulta il pannello prezzi aggiornato sul sito per le tariffe esatte, invece di codificare ipotesi.

Prima di andare in produzione, adotta queste abitudini:

• Retry con backoff. Riprova un numero limitato di volte con ritardo crescente sugli errori transitori (timeout, 5xx); non riprovare gli errori di validazione 4xx.
• Limita il polling. Usa un intervallo fisso e un numero massimo di tentativi. Registra lo stato finale e il tempo impiegato.
• Registra id dei job e prompt. Memorizza id del job, prompt, modello ed eventuali input di riferimento insieme a ogni output, così puoi riprodurre o verificare le esecuzioni.
• Valida gli input il prima possibile. Controlla la lunghezza del prompt e gli URL di riferimento prima dell'invio, per evitare job sprecati.

Con questi controlli, Nano-Banana-2-Lite è un cavallo da tiro prevedibile e a basso costo per la generazione in batch e in background. Consulta la pagina del modello su HiAPI per i parametri e i dettagli tariffari più recenti.