Guida all'API Nano Banana: chiamare nano-banana, nano-banana-2 e nano-banana-pro su HiAPI

Cosa offre la famiglia di modelli Nano Banana

La generazione di immagini raramente si ferma a un'unica impostazione. Nelle fasi iniziali di un progetto servono bozze rapide per esplorare le idee; più avanti servono rendering curati per la consegna. La famiglia Nano Banana su HiAPI è costruita proprio attorno a questa realtà: un'unica interfaccia, tre varianti, ciascuna ottimizzata per un punto diverso della curva qualità-velocità.

La denominazione è intenzionale. nano-banana è l'opzione di base — usala quando stai ancora definendo il prompt o il layout e hai bisogno di un riscontro visivo rapido. nano-banana-2 fa un passo avanti in fedeltà e aderenza al prompt, ed è di solito la scelta quando l'output è vicino alla versione finale ma vuoi ancora iterare. nano-banana-pro è la variante con la massima fedeltà della famiglia, adatta ai rendering finali in cui dettaglio e composizione contano di più.

Ciò che condividono è importante quanto ciò che li distingue. Tutti e tre vengono chiamati tramite lo stesso endpoint HiAPI. Ti autentichi una volta, costruisci la richiesta una volta e, per cambiare, modifichi solo l'identificatore del modello. Questo significa che un'applicazione può inviare una richiesta con il modello di base e poi rieseguire lo stesso prompt con una variante più potente, senza toccare il codice del livello di trasporto.

Una famiglia così mantiene semplice anche l'architettura. Invece di integrare provider separati per ogni livello di qualità, mantieni un unico client, un unico percorso di gestione degli errori e un unico punto di osservazione dell'utilizzo. La scelta del modello diventa un parametro, non un'integrazione.

Perché una famiglia e non un singolo modello

Fasi diverse del flusso di lavoro hanno esigenze diverse. L'esplorazione dei prompt, le bozze di layout e le anteprime per i clienti privilegiano la velocità; le immagini chiave e i materiali di marketing privilegiano la fedeltà. Trattare la scelta del modello come una decisione a runtime ti permette di abbinare ogni fase alla variante giusta senza ricostruire la pipeline.

Scegliere tra nano-banana, nano-banana-2 e nano-banana-pro

Scegli la variante ponendoti due domande: quanto questo output è vicino alla versione finale e quante iterazioni servono per arrivarci? Tutto il resto consegue.

nano-banana: per volumi e esplorazione

Usa il modello di base quando stai ancora decidendo che aspetto dovrebbe avere l'immagine. Riscritture dei prompt, test di stile e miniature di layout beneficiano tutti di un ciclo rapido, e un rendering grezzo spesso risponde alle tue domande meglio di una descrizione. Mantienilo come impostazione predefinita durante lo sviluppo.

nano-banana-2: per iterazioni vicine alla versione finale

Passa a nano-banana-2 quando la composizione è stabile e stai rifinendo i dettagli — spaziatura, fedeltà del soggetto, quanto strettamente l'output segue il prompt. È la scelta intermedia pragmatica: aderenza chiaramente più forte senza dover passare per il percorso di massima fedeltà a ogni anteprima.

nano-banana-pro: per i rendering finali

Riserva nano-banana-pro agli output da consegnare. Immagini chiave, foto di prodotto e qualsiasi cosa che il cliente esaminerà da vicino meritano la variante più potente. Non impostarlo come predefinito — tienilo per l'ultimo passo, così le tue iterazioni esplorative restano economiche.

Una regola di instradamento pratica

Una semplice strategia di escalation funziona per la maggior parte dei team:

• Usa nano-banana come impostazione predefinita per tutti i nuovi prompt.
• Quando la struttura è corretta ma la qualità non basta, promuovi il prompt a nano-banana-2.
• Una volta bloccato il prompt, esegui la versione finale una volta su nano-banana-pro.

Questo rende l'iterazione rapida e prevedibile, e i tuoi modelli di utilizzo facili da capire. La fatturazione segue l'utilizzo e varia in base alla variante, quindi verifica le tariffe e i limiti attuali nella documentazione dei modelli in tempo reale invece di codificare numeri fissi nel codice.

Schemi di prompt validi per tutte le varianti

La cosa più costosa che puoi fare è scrivere prompt che funzionano solo su un modello. Strutturali in modo che cambiarli richieda una sola riga.

Il prompt in quattro blocchi

Scrivi ogni prompt come quattro sezioni etichettate, in questo ordine:

1. Soggetto — cosa c'è nell'immagine, espresso in modo semplice.
2. Stile — il trattamento visivo: fotografia, illustrazione, acquerello, rendering 3D.
3. Composizione — inquadratura, angolazione della camera, posizione, spazio negativo.
4. Vincoli — cosa evitare e qualsiasi requisito imprescindibile.

Un esempio compilato:

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

Poiché i blocchi sono indipendenti, puoi rafforzare lo stile o allentare la composizione senza riscrivere l'intero prompt — e la stessa struttura è facilmente comprensibile a ogni variante della famiglia.

Mantieni i prompt indipendenti dal modello

Evita formulazioni che presuppongono caratteristiche di un modello specifico. Descrivi il risultato che vuoi, non i passaggi che un modello specifico dovrebbe compiere. Quando devi confrontare varianti, cambia solo l'ID del modello e mantieni il prompt identico byte per byte, così il confronto ha senso.

Versiona i prompt come il codice

Archivia i prompt come stringhe in un file di configurazione o in una piccola libreria di prompt, indicizzati per nome e versione. Quando una variante produce output migliori grazie a una messa a punto, registra la modifica. È questo che permette a un prompt di passare da nano-banana a nano-banana-pro al momento della consegna senza sorprese.

I vincoli negativi contano

Se un prompt continua a produrre testo, loghi o oggetti indesiderati, aggiungili esplicitamente al blocco dei vincoli. Tra le varianti, i vincoli negativi chiari sono spesso più affidabili di una formulazione ingegnosa.

Costruire richieste funzionanti su HiAPI

Ogni variante viene chiamata tramite lo stesso endpoint HiAPI. La richiesta ha quattro parti variabili: l'URL di base, l'header di autenticazione, il campo model e il payload.

La forma della richiesta

Una chiamata minima di generazione immagini è questa:

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",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

Conserva la chiave API in una variabile d'ambiente o in un gestore di segreti — mai nel codice sorgente. Il campo model è l'unica cosa da cambiare quando si cambia variante, e il campo prompt contiene la struttura in quattro blocchi della sezione precedente.

In Python, la stessa chiamata richiede poche righe:

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

Cosa contiene la risposta

La risposta contiene il risultato dell'immagine — di solito un URL o un payload codificato — insieme a metadati che identificano il modello che ha elaborato la richiesta. Rileggi e registra il campo del modello: è il modo più economico per sapere a posteriori quale variante ha generato un dato asset.

Verifica i parametri prima della consegna

L'insieme esatto dei parametri opzionali varia tra le varianti ed evolve nel tempo. Prima di codificare qualsiasi cosa oltre model e prompt, consulta la documentazione dei modelli in tempo reale per i nomi dei campi e i valori accettati correnti. Considera non supportato qualsiasi elemento non documentato, invece di indovinare.

Gestire risposte, errori e retry

La generazione di immagini è una chiamata di rete che dietro ha un modello, quindi pianifica le parti che possono fallire.

Valida prima di fidarti

Dopo ogni risposta, controlla tre cose: lo stato HTTP, la presenza di un payload immagine e se il modello restituito corrisponde a quello richiesto. Qualsiasi discrepanza deve fallire in modo esplicito, invece di propagare un asset difettoso a valle.

Riprova solo i fallimenti che vale la pena riprovare

Non ogni errore merita un retry. Un prompt malformato o un nome di modello non valido fallirà allo stesso modo ogni volta — correggi la richiesta. I fallimenti transitori come timeout, reset di connessione e risposte di rate limit meritano un retry.

Usa un backoff esponenziale limitato con jitter:

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

Limita il numero totale di tentativi, così una richiesta danneggiata non entra in un ciclo infinito, e registra il modello e l'hash del prompt a ogni tentativo, per capire se una particolare variante è instabile.

Fallback consapevole

Se una variante continua a fallire, ripiegare su un altro membro della famiglia mantiene viva la pipeline. Poiché tutte e tre condividono la forma della richiesta, il fallback è solo un retry con un valore diverso di model. Decidi l'ordine in anticipo — ad esempio, passare da nano-banana-pro a nano-banana-2 quando una chiamata ad alta fedeltà fallisce ripetutamente — e registra quando scatta il fallback, così noti i pattern.

Rendi visibili i fallimenti

Valida il payload restituito prima di archiviarlo ed emetti metriche per retry e fallback. Quando il tasso di errori sale, vuoi saperlo prima che un lotto di attività produca silenziosamente output vuoti.

Rafforzamento prima della consegna

Prima di mostrare la generazione di immagini agli utenti, ripassa questa checklist.

Conferma ID e parametri

Gli identificatori dei modelli cambiano. Ricontrolla i nomi attuali dei modelli della famiglia Nano Banana e verifica ogni parametro opzionale con la documentazione in tempo reale. Non consegnare valori che esistono solo in esempi obsoleti.

Configurazione centralizzata

Metti gli ID dei modelli, i template dei prompt e i limiti di retry in un unico modulo di configurazione. Quando promuovi un prompt da nano-banana a nano-banana-pro, dovrebbe essere una modifica di configurazione, non una modifica al codice sparsa su più file.

Registra le informazioni importanti

Per ogni chiamata registra modello, versione del prompt, stato della risposta, latenza e se si sono verificati retry o fallback. Calcola l'hash dei prompt lunghi per mantenere leggibili i log. È questo che permette di rispondere alla domanda "perché questa immagine ieri sembrava diversa?".

Monitora l'utilizzo durante lo scaling

Poiché la fatturazione segue l'utilizzo, tieni d'occhio il numero di chiamate e la combinazione di varianti. Far salire silenziosamente ogni richiesta a nano-banana-pro può trasformare uno strumento esplorativo in un problema di costi. Instrada consapevolmente: varianti economiche per l'iterazione, varianti più potenti per l'output finale.

Testa l'endpoint

Scrivi un piccolo smoke test che chiami ogni variante una volta con un prompt fisso e verifichi che la risposta sia valida. Eseguilo prima di ogni rilascio contro la documentazione corrente, così le modifiche ai modelli non ti coglieranno mai di sorpresa in produzione.

Consegnata con un unico client, una libreria di prompt condivisa e una strategia di instradamento consapevole, la famiglia Nano Banana su HiAPI diventa l'unica dipendenza da cui passare dalle bozze ai rendering finali senza riscrivere l'integrazione.