I tre valori necessari per ogni integrazione
Quasi ogni guida all'integrazione nanobanana api si riduce a compilare gli stessi tre campi in punti diversi. Il servizio usa il protocollo OpenAI chat-completions, quindi uno strumento che permette di sovrascrivere l'endpoint OpenAI può comunicare con esso.
| Campo | Valore |
|---|---|
| URL di base | https://api.nanobananaapis.com/v1 |
| Chiave API | La tua chiave, inviata come Authorization: Bearer <key> |
| ID modello | uncensored |
Una nota sull'ambito prima di iniziare. Questo è un modello linguistico testuale, quindi non funzionerà nei punti che si aspettano generazione di immagini, voce o embedding. I metodi supportati sono POST /v1/chat/completions e GET /v1/models. Se uno strumento richiede un modello embedding per la ricerca, punta quella parte a un altro provider.
Ottieni una chiave dalla pagina delle chiavi API. I nuovi account possono richiedere $0,50 di credito di prova con un clic, senza carta, valido per 7 giorni.
Testa l'endpoint prima di toccare qualsiasi strumento
Quando un'integrazione fallisce, le persone danno la colpa allo strumento. Nella maggior parte dei casi la chiave o l'URL sono sbagliati. Un test curl di trenta secondi elimina ogni dubbio. Prima elenca i modelli:
curl https://api.nanobananaapis.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
Poi invia una breve richiesta di chat:
curl https://api.nanobananaapis.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with the word ready."}],"max_tokens":10}'
Se entrambi funzionano, l'endpoint e la chiave sono a posto e qualsiasi errore successivo deriva da come è configurato uno strumento. Se la prima chiamata restituisce 401, la chiave è sbagliata o manca la parola Bearer nell'header. Un 404 di solito significa che all'URL manca /v1 o ha un percorso extra.
SillyTavern
SillyTavern è un'interfaccia per roleplay e chat con personaggi, e permette di aggiungere un endpoint compatibile con OpenAI. Le etichette del menu cambiano tra le versioni, quindi tratta i passaggi come una mappa piuttosto che come testo esatto.
- Apri il pannello di connessione API e scegli Chat Completion come tipo di API.
- Seleziona la fonte Custom (OpenAI-compatible).
- Incolla
https://api.nanobananaapis.com/v1come URL dell'endpoint. - Incolla la tua chiave nel campo chiave.
- Inserisci
uncensoredcome nome del modello, o premi il pulsante Connetti e selezionalo dall'elenco restituito daGET /v1/models. - Premi Connetti e invia un messaggio di test.
Due note di configurazione. SillyTavern invia cronologie lunghe con le carte dei personaggi, quindi tieni d'occhio la finestra di contesto da 100.000 token, condivisa tra prompt e risposta. E se usi chat di gruppo che avviano più richieste contemporaneamente, ricorda il limite di 8 richieste parallele con una chiave completa (2 con una chiave di prova). Le configurazioni per il roleplay e i compagni sono per adulti; il modello non produrrà contenuti sessuali che coinvolgono i minorenni sotto alcun prompt.
LangChain
In Python, il pacchetto langchain-openai fornisce ChatOpenAI, che accetta un URL base personalizzato. Installalo con pip install langchain-openai.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
model="uncensored",
temperature=0.7,
)
print(llm.invoke("Give me three names for a fictional smuggler ship.").content)
Le catene, i template di prompt e i parser di output funzionano allo stesso modo dopo, poiché si concentrano solo sull'interfaccia chat. La chiamata di funzioni segue il percorso standard, quindi llm.bind_tools([...]) invia tools nella richiesta. Testa una singola chiamata di funzione prima di costruire un agente attorno ad essa e limita la parallelizzazione dell'agente a 8. Un grafo che si dirama in venti rami andrà incontro all'errore concurrency.
Il pacchetto JavaScript @langchain/openai adotta la stessa idea tramite un'opzione configuration: { baseURL } su ChatOpenAI.
Cursor e altri editor
Cursor, come diversi altri editor di codice, ha un'area delle impostazioni per i modelli dove puoi fornire la tua chiave API OpenAI e sovrascrivere l'URL base. Più o meno: apri le impostazioni del modello, abilita l'opzione chiave OpenAI personalizzata, imposta l'URL base di override su https://api.nanobananaapis.com/v1, incolla la tua chiave e aggiungi uncensored come nome di modello personalizzato.
Sii realistico su cosa ti offre questo. Gli editor costruiscono alcune funzionalità, come il completamento in linea, attorno ai propri backend e a nomi di modello specifici, quindi un endpoint personalizzato potrebbe applicarsi solo alla chat o a un sottoinsieme di comandi. Le opzioni esatte cambiano tra le versioni, quindi controlla la documentazione corrente dell'editor. Se una funzionalità richiede qualcosa che questa API non offre, come embedding o input immagine, non funzionerà attraverso questo endpoint.
Lo stesso schema si applica ad altri client compatibili con OpenAI come Open WebUI, Continue e interfacce chat simili: trova il campo per un endpoint OpenAI personalizzato, inserisci i tre valori e testa.
SDK base e variabili d'ambiente
Se scrivi il tuo codice, gli SDK ufficiali leggono le variabili d'ambiente standard, il che ti permette di cambiare endpoint senza toccare i file sorgente. Negli SDK Python e Node, impostare OPENAI_BASE_URL e OPENAI_API_KEY è sufficiente.
export OPENAI_BASE_URL="https://api.nanobananaapis.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
python app.py # app.py calls client.chat.completions.create(model="uncensored", ...)
Un client esplicito in Node appare così:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.nanobananaapis.com/v1",
apiKey: process.env.NANOBANANA_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Draft a short product description for a paper lantern." }],
stream: true,
});
for await (const part of stream) {
process.stdout.write(part.choices[0]?.delta?.content ?? "");
}
Lo streaming arriva tramite SSE con l'utilizzo riportato alla fine. I dettagli completi sui parametri sono nella pagina della documentazione, e l'articolo sulla generazione di prompt mostra come collegare una fase testuale a una pipeline di immagini.
Risoluzione degli errori comuni
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| 401 Non autorizzato | Chiave sbagliata o header Bearer mancante | Ricopia la chiave e testa con curl |
| 404 Non trovato | Base URL senza /v1 o percorso duplicato | Usa esattamente https://api.nanobananaapis.com/v1 |
| Modello non trovato | Lo strumento ha come predefinito il nome del modello del vendor | Imposta il modello su uncensored |
429 con rate_limited | Più di 300 richieste al minuto (60 in prova) | Rallenta e riprova |
429 con concurrency | Più di 8 richieste simultanee (2 nella prova) | Riduci la parallelizzazione |
| 429 con Retry-After: 5 | Sovraccarico temporaneo | Attendi cinque secondi e riprova |
| Richiesta troppo grande | Body superiore a 8 MB | Riduci allegati o cronologia |
Tieni presente che una richiesta in streaming mantiene la sua slot di concorrenza fino alla fine dello streaming, quindi un editor che abbandona gli streaming può sembrare che stia raggiungendo il limite quando non è occupato. Registra l'intestazione X-Request-Id dalle chiamate fallite; è la prima cosa che il supporto chiederà.
Per quanto riguarda i costi, un messaggio di chat tipico con 2.000 token in input e 500 in output costa $0,00055 a $0,15 e $0,50 per 1M di token, e le richieste fallite non vengono addebitate. La pagina dei prezzi copre i ricarichi da $20 a $500 e i livelli bonus.
Chiavi, sicurezza e visibilità dei dati
Ogni integrazione memorizza la tua chiave da qualche parte, e alcune la memorizzano meglio di altre. In un'interfaccia desktop la chiave è in un file di impostazioni locale. In uno strumento basato sul browser potrebbe essere salvata nel browser. In un editor si trova nella configurazione dell'app. Scopri quale stai usando prima di condividere lo schermo, di commettere un file nascosto o di prestare un laptop a qualcuno.
Alcune regole rendono la gestione più semplice. Usa una chiave per strumento dove possibile, così potrai sostituirne una singola senza rompere le altre. Non incollare mai una chiave in un tracker di problemi pubblico quando chiedi aiuto; condividi invece l'ID della richiesta. Se una chiave viene compromessa, sostituila dalla pagina delle chiavi e aggiorna i tuoi strumenti. I prompt inviati tramite l'API non vengono utilizzati per l'addestramento, e la pagina privacy descrive il resto della gestione dei dati.
Se ospiti un'interfaccia per altre persone, non distribuire la tua chiave al browser. Metti un piccolo server tra i tuoi utenti e l'API, aggiungi i tuoi limiti lì e mantieni la chiave sul server. I tuoi utenti condividono poi le tue 8 richieste parallele, quindi pianifica quante persone possono chattare contemporaneamente.
Quale strumento si adatta a quale lavoro
Poiché l'integrazione è la stessa ovunque, la scelta dello strumento dipende da cosa stai creando.
- SillyTavern o un simile front-end per chat è adatto per chat di personaggi, narrativa e roleplay per adulti, dove desideri un'interfaccia curata e schede personaggio senza scrivere codice.
- LangChain è adatto per pipeline nel codice: loader, template di prompt, parser e catene multi-step. Aggiunge struttura al costo di una dipendenza in più.
- Una chiamata SDK semplice è adatta per piccoli script e servizi. Se il tuo compito è un prompt in input e una risposta in output, il pacchetto OpenAI da solo è meno da mantenere rispetto a un framework.
- Un editor come Cursor è adatto per la chat sul codice. Verifica quali delle sue funzionalità accettano un endpoint personalizzato prima di farvi affidamento.
Inizia con il test curl semplice, poi l'SDK, poi aggiungi un framework solo quando ne hai bisogno. Passare in seguito è facile, poiché i tre valori non cambiano mai. Per una prima richiesta e l'elenco completo dei parametri, leggi la documentazione.
