Guida all'uso
Guida alla generazione di immagini da testo con Nano Banana versione base: formato, spazio negativo e uso dei prompt
Usare i campi aspect_ratio e prompt dell'API delle attività per generare immagini con composizione chiara per banner e card social
In questa pagina
Posizionamento e limiti di questa linea
nano-banana su HiAPI è una linea di generazione di immagini da testo (text-to-image), inviata come attività asincrona: i campi di input nella richiesta sono tutti raccolti sotto l'oggetto input e, dopo l'invio, il risultato si recupera come attività. È adatta a scenari con esigenze di illustrazioni in batch, ad esempio banner operativi, card social, bozze di illustrazioni per articoli. Questo articolo tratta solo la versione base e non riguarda altri modelli della stessa serie.
I campi disponibili sono pochi, quindi chiariamo subito il contratto: prompt è una stringa obbligatoria, lunghezza 1–5000 caratteri; aspect_ratio è opzionale, valore predefinito auto, con valori enum auto, 1:1, 16:9, 9:16, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9; output_format è opzionale png o jpeg, predefinito png. Il vecchio campo image_size è deprecato: per specificare il formato desiderato usare aspect_ratio.
Va chiarito che questa linea non espone campi come resolution, quality, width, height, seed né il caricamento di immagini di riferimento. Non inserire queste chiavi in input secondo le abitudini di altri modelli di immagini e non dare per scontato che vengano ignorate silenziosamente. Allo stesso modo, aspect_ratio serve a specificare il rapporto d'aspetto desiderato e non garantisce dimensioni in pixel fisse; per il formato e i pixel effettivi fare riferimento all'immagine restituita e verificare prima della consegna.

Contratto dei campi e un frammento input minimo
Di seguito un frammento input contenente solo i campi sopra descritti, per illustrare la gerarchia dei campi. Non è una richiesta HTTP completa: non sono indicati endpoint, header di autenticazione e modalità di polling dell'attività; per questi fare riferimento alla documentazione delle API di HiAPI.
{
"input": {
"prompt": "Illustrazione geometrica piatta con composizione orizzontale, sfondo color sabbia calda, il terzo destro occupato da blocchi a gradoni, spazio negativo a sinistra, nessun testo nell'immagine.",
"aspect_ratio": "16:9",
"output_format": "png"
}
}
Il modo in cui si scrive il prompt influisce sul grado di controllo dell'immagine. Un ordine pratico è: prima soggetto e scena, poi composizione e posizione del soggetto, quindi area di spazio negativo, infine colori, luce e stile. Se nell'immagine non servono testi, scrivere esplicitamente "nell'immagine non compaiono testi, lettere o numeri" fa risparmiare rispetto a correggere dopo. Sulla lunghezza non serve riempire i 5000 caratteri: basta esprimere chiaramente i vincoli chiave; accumuli troppo lunghi finiscono per diluire i punti importanti.
La scelta di output_format dipende dalla catena di consegna: png è adatto alla conservazione senza perdita e alle modifiche successive, jpeg alla consegna con compressione lossy. Il valore predefinito è png; se a valle la dimensione è critica, ricordarsi di impostare esplicitamente jpeg. Va precisato che poter scegliere png non significa che il modello abbia generato un canale alfa trasparente; questa linea non dichiara capacità né campi per lo sfondo trasparente e non garantisce rimozione dello sfondo o output trasparenti.
Formato e spazio negativo: prima definire il layout, poi scrivere il prompt
Lo spazio negativo non è "vuoto", ma lo spazio riservato a titoli, pulsanti e badge. Le strategie di spazio negativo variano con il formato e nel prompt lo spazio negativo va descritto come parte della composizione.
- Banner 16:9: comune per immagini di testata del sito e copertine di articoli. Si consiglia di spostare il soggetto sul terzo destro o sinistro e lasciare sull'altro lato un'area continua a bassa informazione, evitando che il soggetto copra il titolo. Nel prompt si può scrivere "sul lato sinistro dell'immagine lasciare un'area a basso contrasto larga circa un terzo".
- Card social 1:1: soggetto centrato, con spazio di respiro sopra e sotto; gli elementi ai bordi non devono toccare il margine, per evitare tagli nel ritaglio del feed.
- Verticale 9:16: lasciare una fascia in alto e una in basso per titolo e firma; collocare il soggetto nella parte centrale, evitando sovrapposizioni con le aree di testo alle estremità.
- 4:5 e 3:4: proporzioni comuni vicine a stampa e feed, lo spazio negativo può essere minore, ma si consiglia comunque di mantenere un margine di sicurezza sui quattro lati.
- Ultra-wide 21:9: spazio orizzontale abbondante, adatto a disporre più elementi in ritmo, ma le estremità si tagliano facilmente: il soggetto importante non deve toccare i bordi.
- auto: il rapporto è deciso dal servizio, adatto all'esplorazione iniziale; entrando in produzione in batch, si consiglia di specificare esplicitamente il rapporto per ridurre le rilavorazioni di layout.
Va ribadito: il rapporto non è la dimensione in pixel. aspect_ratio imposta il rapporto d'aspetto desiderato: 16:9 non significa una dimensione fissa in pixel (ad esempio 1920×1080). Dopo aver ricevuto l'immagine, verificare che il formato effettivo corrisponda alle aspettative; se a valle esistono requisiti rigidi di dimensione, ridimensionare o ritagliare autonomamente, lasciando margini di sicurezza abbondanti già in fase di prompt.
Due esempi di prompt direttamente modificabili
I due testi seguenti sono formulazioni da verificare, non conclusioni testate. Si consiglia di chiamare una volta ciascuno, osservare se posizione del soggetto e spazio negativo corrispondono alle aspettative, quindi adattare al progetto.
Spazio negativo per banner (16:9):
"Illustrazione geometrica piatta con composizione orizzontale, sfondo color sabbia calda. Nel terzo destro dell'immagine inserire una struttura a gradoni composta da blocchi color terracotta, ocra e marrone scuro, che scendono gradualmente da sinistra a destra con bordi netti; nei due terzi sinistri mantenere un'area di spazio negativo a basso contrasto e priva di dettagli, con solo una tenue banda orizzontale come transizione. Palette complessivamente sobria, senza rumore di gradiente, senza testi, lettere, numeri o loghi, composizione equilibrata, adatta come immagine di testata per articoli."
Card social (1:1):
"Illustrazione minimalista con composizione quadrata, sfondo beige chiaro. Al centro dell'immagine inserire un segno astratto formato da tre archi sovrapposti, nei colori verde inchiostro scuro e ocra, con spessore delle linee uniforme; attorno al segno mantenere uno spazio negativo uniforme, leggermente maggiore sopra e sotto che a destra e sinistra, per facilitare la sovrapposizione successiva del titolo. Sfondo pulito, senza texture, senza ombre, senza testi, lettere, numeri o loghi, atmosfera complessivamente tranquilla e sobria."
Entrambi i prompt descrivono lo "spazio negativo" come descrizione spaziale eseguibile, non con una frase come "più spazio negativo". Se il soggetto generato tocca ancora i bordi, correggere prima gli indicatori di posizione e le percentuali nella descrizione, invece di aggiungere aggettivi.
Iterazione graduale: cambiare una sola variabile alla volta
L'errore più comune nella generazione in batch è modificare insieme prompt, rapporto e formato, senza poter capire quale modifica abbia causato il cambiamento. Un approccio più stabile è convergere per passi.
- Primo passo: fissare aspect_ratio e output_format e usare un prompt breve per verificare che il soggetto sia compreso correttamente.
- Secondo passo: aggiungere la descrizione della composizione: posizione del soggetto, percentuale dell'immagine occupata, area di spazio negativo.
- Terzo passo: aggiungere colori, luce e stile, osservando se comprimono lo spazio negativo.
- Quarto passo: organizzare la descrizione stabilizzata in un template; in batch sostituire solo soggetto e palette, senza modificare le frasi strutturali.
Dopo ogni chiamata annotare prompt, aspect_ratio, output_format e differenze nel risultato. La registrazione stessa è un patrimonio: quando un batch presenta scostamenti sistematici, dai registri si può individuare rapidamente se si è scelto il rapporto sbagliato, se è cambiata la struttura del prompt o se ci sono errori di ortografia nei campi.
Autoverifica alla consegna e gestione degli errori
Dopo aver ricevuto l'immagine, verificare i seguenti punti: il formato corrisponde al rapporto target di aspect_ratio; il soggetto è completo e non ritagliato; l'area di testo riservata è sufficientemente pulita; nell'immagine non compaiono testi indesiderati o elementi simili a watermark; il formato di output corrisponde ai requisiti a valle. Se destinata a banner, visualizzare in anteprima anche alla dimensione reale della pagina, verificando che il titolo sovrapposto non copra il soggetto.
In caso di attività fallita o risultato deviato, controllare in ordine: se prompt è vuoto o supera 1–5000 caratteri; se aspect_ratio è tra i valori enum; se output_format usa solo png o jpeg; se è stato usato per errore il deprecato image_size; se sono stati passati campi non esposti da questa linea. Dopo aver confermato che i parametri sono corretti, semplificare il prompt e riprovare, invece di inviare ripetutamente lo stesso input. Se gli scostamenti si ripetono più volte, ridurre al minimo gli elementi dell'immagine e aggiungerli di nuovo uno per uno.
Ultima nota: le illustrazioni nell'articolo sono solo schematiche, servono a illustrare il flusso "input attraverso il canale delle attività che produce un'immagine" e non sono output reali di nano-banana. Tutti i prompt e le combinazioni di campi vanno verificati con chiamate proprie prima di entrare nel processo produttivo. Dettagli del modello in /models/nano-banana.
Articoli correlati
Vedi tutti gli articoli →-
Guida all'uso
Gestione delle risposte di Kimi K3 in pratica: JSON completo, interruzioni dello streaming e limiti dei tentativi
-
Guida all'uso
Estrazione strutturata con GLM 5.3 in pratica: dare a ogni campo JSON una base nel testo originale
Estrarre campi con la modalità JSON object, affidandosi a valori mancanti, citazioni e validazione di business per fermare gli errori prima dell'inserimento nel database
-
Guida all'uso
Guida alla produzione di brani brevi con MiniMax Music 3: come scrivere separatamente testo, tag di sezione e brief di arrangiamento
Progettare una richiesta per un brano breve riproducibile partendo dai due input obbligatori previsti dal contratto attuale