Guida all'uso

Come si usa l'API di Nano Banana Pro? Crea la tua prima immagine in 5 minuti

4 passaggi per la prova online, 4 passaggi per l'integrazione API, con esempi curl e Python pronti da eseguire, esempi di modifica con immagini di riferimento e una guida rapida agli errori più comuni.

Oct 12, 2026

TL;DR

Cos'è: Gemini 3 Pro Image di Google, la fascia flagship della serie Nano Banana, con lo stesso model ID nano-banana-pro per la generazione da testo e la modifica con immagini di riferimento. È già disponibile su HiAPI: apri la pagina del modello, inserisci il prompt e genera; i nuovi utenti ricevono 200 crediti alla registrazione, sufficienti al prezzo standard per 1 immagine 2K.
Quanto costa: fatturazione per immagine, 1K e 2K allo stesso prezzo di $0.057, 4K a $0.1, calcolato per ogni immagine in output, circa il 57%–58% in meno rispetto al prezzo standard ufficiale di Google, senza sovrapprezzo per le immagini di riferimento.
Come si chiama l'API: POST https://api.hiapi.ai/v1/tasks, model impostato a nano-banana-pro, una volta ottenuto il taskId puoi interrogare o attendere il callback, quindi scaricare data.output[0].url.

I costi dei token di input di Google sono separati; il confronto di prezzo sopra si riferisce al prezzo per immagine in output.

Cosa può fare Nano Banana Pro?

2K senza sovrapprezzo. 1K e 2K costano entrambi $0.057 per immagine, quindi puoi generare direttamente in 2K; 4K costa $0.1 per immagine, da riservare a stampa e grandi schermi.
Testo dentro l'immagine. Frasi brevi in inglese come insegne, titoli di poster e date si scrivono direttamente nel prompt; l'insegna in foglia d'oro qui sotto ha entrambe le righe di testo corrette al primo colpo, senza alcun post-processing.
Fino a 8 immagini di riferimento. Con solo il prompt è text-to-image; aggiungendo image_input diventa modifica o fusione di più immagini, con lo stesso model ID e senza dover mantenere due set di codice.
10 formati più auto. Sono disponibili i rapporti più usati come 1:1, 4:5, 3:4, 9:16, 16:9, 21:9. Per immagini allungate come 1:4 o 8:1, o per caricare più di 8 immagini di riferimento in una volta, scegli Nano Banana 2 (fino a 14 immagini).

Immagine originale di Nano Banana Pro, non ritoccata, output 1536×2752.

A hand-painted gold-leaf sign in a modern specialty coffee shop window, elegant serif lettering reading 'MORNING BREW CO.' with a small script subtitle 'est. 2024' beneath it, warm natural daylight streaming through the glass, soft bokeh reflections of a city street, photorealistic commercial photography, crisp perfectly legible typography with correct spelling, shallow depth of field, editorial lighting

Genera con questo prompt →, formato 9:16, risoluzione 2K.

Due percorsi per iniziare: prova online o API?

Se vuoi prima vedere il risultato, scegli la prova online; se devi integrare nel prodotto, scegli l'API. Entrambi i percorsi usano lo stesso modello e gli stessi prezzi.

Prova online (circa 1 minuto)

Apri la pagina del modello Nano Banana Pro, oppure clicca direttamente il link sotto l'immagine dell'insegna qui sopra: il prompt verrà compilato automaticamente.
Registrati o accedi; il nuovo account include 200 crediti.
Scegli formato e risoluzione; a prezzo standard 1K e 2K costano entrambi 114 crediti per immagine.
Clicca esegui e, se il risultato ti soddisfa, scarica.

Integrazione API (circa 5 minuti)

Crea una API Key nella console HiAPI (sk-...).
POST /v1/tasks per creare il task; nella risposta ottieni data.taskId.
Interroga con GET /v1/tasks/{id}, oppure includi callback.url nella richiesta e attendi la notifica.
Quando data.status diventa success, scarica l'immagine da data.output[0].url.

2K costa $0.057 per immagine: con $10 puoi generare circa 175 immagini. In promozione limitata per la Festa del Programmatore con il 50% di sconto fino alle 00:00 ora di Pechino del 2026-11-09, durante il periodo 1K e 2K costano $0.0285 per immagine, sempre circa 350 immagini con $10. I parametri completi sono nella documentazione in cinese.

Prima immagine: versione curl

Crea il task:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "input": {
      "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
      "aspect_ratio": "16:9",
      "resolution": "2K",
      "output_format": "png"
    }
  }'

L'ID del task restituito si trova in data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Interroga il risultato:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

L'unico campo obbligatorio è prompt. aspect_ratio è auto per impostazione predefinita, resolution è 1K e output_format è png, ma puoi scegliere anche jpg. 1K e 2K costano uguale: consigliamo di scrivere "resolution": "2K" in ogni richiesta.

Prima immagine: versione Python

Prima installa requests (python3 -m pip install requests) e imposta HIAPI_API_KEY nel terminale (export HIAPI_API_KEY="sk-YOUR_KEY"). L'esempio seguente crea il task, esegue il polling per un massimo di 10 minuti e poi scarica l'immagine; dopo il timeout conserva il taskId per continuare a interrogare:

import os
import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "nano-banana-pro",
    "input": {
        "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-pro.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

Modifica con immagine di riferimento: basta aggiungere un campo

Aggiungendo image_input dentro input, la stessa richiesta diventa una modifica. Qui usiamo come riferimento un poster scientifico generato da Nano Banana Pro e cambiamo solo la riga della data:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "input": {
      "prompt": "Keep this exact poster: layout, planet, observatory, visitor, colors and headline. Change only the date line to SAT 24 OCT in the same typography and color. No other words.",
      "image_input": ["https://static.hiapi.ai/blog/gpt-image-2-vs-nano-banana-pro/0dba86ff979d-nano-pro-science.png"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

image_input accetta fino a 8 URL pubblici, supporta JPEG, PNG e WebP. Nel prompt separa ciò che va "modificato" da ciò che va "conservato": più i vincoli di conservazione sono specifici, più l'immagine originale resta stabile.

3 cose da tenere presenti prima della messa in produzione

Sul server usa il callback. Aggiungi al livello superiore del body "callback": {"url": "https://yourapp.com/webhook", "when": "final"}: il task notifica automaticamente al termine, evitando il polling; i callback possono arrivare più volte, deduplica per taskId.
In caso di timeout non ripetere il POST. Ogni POST /v1/tasks crea un nuovo task e viene fatturato separatamente. Salva prima il taskId e deduplica nel tuo sistema prima di riprovare.
Scrivi esplicitamente resolution in ogni richiesta. Il valore predefinito è 1K; 2K ha lo stesso prezzo, quindi per la versione finale puoi scegliere direttamente 2K; 4K costa di più, usalo solo nella fase di consegna.

Errori comuni, uno per riga

400, campo non consentito → nome del campo scritto male, oppure campo di un altro modello (ad esempio image_urls) → usa image_input.
400, valore di aspect_ratio non valido → formato fuori dalla lista (come 8:1) → scegli tra i 10 formati e auto; per immagini allungate passa a Nano Banana 2.
401 → Key mancante, errata o revocata → controlla l'header Authorization: Bearer sk-... e, se necessario, ricrea la Key nella console.
Creazione riuscita ma task in stato fail → controlla l'errore restituito dal task; se l'immagine di riferimento non si apre o il formato non è supportato, invia di nuovo un JPEG, PNG o WebP accessibile pubblicamente.
Il link dell'immagine non si apre dopo la scadenza → i link di output hanno una validità → scarica subito il risultato e salva il file stesso.

I task falliti non vengono addebitati.

Domande frequenti

Come scegliere tra Nano Banana Pro e Nano Banana 2? Per il 2K costano uguale, entrambi $0.057 per immagine. Se ti servono formati allungati o più di 8 immagini di riferimento, scegli Nano Banana 2; se vuoi la fascia flagship della serie Nano Banana per il key visual del brand, scegli Pro.

Le immagini di riferimento hanno un costo aggiuntivo? No. Il prezzo dipende solo dalla risoluzione di output: è identico con 1 o 8 immagini di riferimento.

Si può passare direttamente da Nano Banana 2? Sì. I nomi dei campi sono gli stessi (prompt, image_input, aspect_ratio, resolution, output_format): basta cambiare model in nano-banana-pro; il formato deve essere tra i 10 supportati da Pro.

Quante immagini si generano in una volta? Un task genera un'immagine. Per più immagini, crea più task in parallelo; la fatturazione è per immagine.

Articoli della serie Nano Banana Pro

Prova subito: clicca Genera con questo prompt → sotto l'immagine dell'insegna qui sopra: il prompt è già compilato, scegli 9:16 e 2K, sostituisci il testo tra virgolette con il nome della tua attività e avvia.

TagGenerazione di immagini guida-api Integrazione API Esercitazione