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

Nano-Banana-2-Lite è la versione economica della famiglia di modelli di immagini Nano-Banana su hiapi: adotta lo stesso workflow basato su task dei suoi fratelli maggiori, costa meno per singola immagine e supporta sia la generazione testo-immagine sia l'editing con immagine di riferimento. Questa guida ti accompagna attraverso un flusso di integrazione completo e funzionante — crea il task, esegui il polling, scarica il risultato — con esempi in curl e Python, e illustra i dettagli dello schema in cui differisce da Nano-Banana-2 e Nano-Banana-Pro.

Cosa costruirai e cosa ti serve

Obiettivo: inviare un prompt a Nano-Banana-2-Lite, attendere la generazione dell'immagine e salvarla su disco.

Ti serve solo una cosa: una chiave API di hiapi (sk-...). Ottienila dalla tua dashboard hiapi. Il costo per singola immagine è elencato nella pagina dei prezzi e nella pagina del modello Nano Banana 2 Lite.

Tutti i modelli di immagini su hiapi funzionano tramite un'API a task asincrona unificata: crei un task con POST /v1/tasks, poi esegui il polling di GET /v1/tasks/{id} oppure ricevi un webhook quando il task è completato.

Richiesta minima funzionante (curl)

Crea il task:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
      "aspect_ratio": "3:2"
    }
  }'

L'id del task restituito nella risposta si trova in data.taskId. Esegui il polling:

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

Quando data.status è "success", l'URL dell'immagine si trova in data.output[0].url. Scaricala subito: gli URL di output sono firmati e hanno una scadenza (expireAt), quindi salva i byte, non il link.

Due regole dello schema che spesso ingannano, direttamente dalla validazione dell'API stessa:

• L'id del modello è sensibile alle maiuscole. "model": "nano-banana-2-lite" restituisce 400 MODEL_UNAVAILABLE ("model not available via /v1/tasks"). Usa l'id esatto Nano-Banana-2-Lite.
• prompt e aspect_ratio sono entrambi obbligatori. Omettere uno dei due comporta un 400 INVALID_REQUEST con messaggio missing required field. Valori validi per aspect_ratio: auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1.

Lo stesso flusso in Python

Nessun SDK necessario — l'API a task è puro JSON su HTTPS:

import os
import time

import requests

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

# 1. Create the task
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until the task reaches a terminal state
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Download immediately — output URLs are signed and expire
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

Editing con immagine di riferimento: image_urls, non image_input

Nano-Banana-2-Lite supporta l'editing delle immagini, ma il suo campo per le immagini di riferimento è image_urls — un array con un massimo di 10 URL accessibili pubblicamente:

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "Replace the background with a clean white studio backdrop, keep the product unchanged",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

Questo è l'inciampo più comune della famiglia: Nano-Banana-2 e Nano-Banana-Pro usano image_input per lo stesso scopo, mentre Lite rifiuta quel campo (additional properties 'image_input' not allowed). Nomi di campo come input_urls, images o reference_images vengono rifiutati su tutti e tre i modelli. Se sposti il codice tra i livelli, di solito l'unica modifica necessaria è proprio questo rinomina del campo.

Lite vs. Nano-Banana-2 vs. Pro: differenze di schema importanti

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
Input obbligatori	prompt, aspect_ratio	prompt	prompt
Immagine di riferimento	image_urls (≤10)	image_input	image_input
Controllo resolution	Non accettato	Accettato	Accettato

Lite mantiene un'interfaccia estremamente essenziale: prompt, aspect ratio, immagini di riferimento opzionali. Niente resolution, seed, n o negative_prompt — inviare uno di questi comporta un errore di validazione additional properties ... not allowed. Se ti serve il controllo esplicito della risoluzione (1K/2K/4K) o un livello di fedeltà superiore, passa a Nano-Banana-2 o Nano-Banana-Pro; se invece generi in batch — miniature, bozze, cicli iterativi, varianti in serie — il minor costo per immagine di Lite è proprio il suo senso.

Hardening per la produzione

Usa i webhook invece del polling quando possibile. Quando crei il task aggiungi un blocco callback: hiapi invierà il risultato finale al tuo endpoint:

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when accetta solo "final" — ricevi un solo callback, sia in caso di successo sia di fallimento. Il polling va bene per script e notebook; i callback sono più adatti ai server perché ti evitano di gestire cicli di polling e timeout. Se esegui comunque il polling, un intervallo di 2–5 secondi con una scadenza rigida (come nell'esempio Python) è sufficiente.

Gestisci due livelli di errori. I fallimenti a livello di richiesta vengono restituiti come errori HTTP — una chiave non valida o non autorizzata restituisce 401 con {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}, gli errori di schema restituiscono 400 INVALID_REQUEST con il messaggio di validazione esatto. I fallimenti a livello di task arrivano con status: "fail" e un oggetto error sul task stesso; gestisci entrambi i percorsi nel tuo codice.

Rendi i retry idempotenti. La creazione del task non è idempotente — riprovare una richiesta di creazione scaduta può generare due task (e due addebiti). Persisti il taskId appena ricevuto e, dopo un riavvio, continua il polling dell'id esistente invece di ricrearlo ciecamente.

Salva i byte, non gli URL. Gli URL di output scadono. Prima di qualsiasi altra operazione sull'immagine, scaricala e mettila nello tuo storage.

Letture correlate

• Pagina del modello Nano Banana 2 Lite — parametri, prezzi in tempo reale, playground
• GPT Image 2 vs Nano Banana 2: confronto affiancato con lo stesso prompt
• Mantenere la coerenza dei personaggi con Nano-Banana su hiapi
• Documentazione hiapi e prezzi

FAQ

Perché ricevo "model not available via /v1/tasks"? L'id del modello è sensibile alle maiuscole. Usa esattamente Nano-Banana-2-Lite; le varianti minuscole vengono rifiutate con 400 MODEL_UNAVAILABLE.

Nano-Banana-2-Lite supporta l'editing immagine-immagine? Sì. Passa le immagini di riferimento nell'array image_urls (massimo 10 URL). Può gestire sostituzione dello sfondo, trasferimento di stile e workflow di editing guidati da prompt.

Perché il mio codice per Nano-Banana-2 fallisce su Lite con "additional properties 'image_input' not allowed"? Livelli diversi usano nomi di campo diversi per le immagini di riferimento: Lite si aspetta image_urls, mentre Nano-Banana-2 e Pro si aspettano image_input. Rinomina il campo quando cambi livello.

Posso impostare resolution, seed o il numero di immagini? Su Lite no — il suo schema di input accetta solo prompt, aspect_ratio e image_urls. Per il controllo di resolution a 1K/2K/4K, usa Nano-Banana-2 o Nano-Banana-Pro.

Quanto durano gli URL delle immagini di output? Sono URL firmati con timestamp di scadenza (expireAt nell'oggetto di output). Scarica subito i byte e salvali nel tuo storage; non fare mai hotlink dell'output del task.

Cosa significa 401 permission_denied? La tua chiave API non è valida oppure non è abilitata per questo modello. Controlla la chiave nella tua dashboard e assicurati di inviarla come Authorization: Bearer sk-....

Quanto costa Nano-Banana-2-Lite per immagine? La fatturazione è a consumo, per immagine, posizionata come il livello più economico della famiglia Nano-Banana. Le tariffe attuali sono nella pagina dei prezzi.