Les trois valeurs nécessaires à toute intégration
Presque tous les guides sur l'intégration API nanobanana se résument à remplir les mêmes trois champs à des endroits différents. Le service utilise le protocole OpenAI chat-completions, donc un outil permettant de remplacer l'endpoint OpenAI peut s'y connecter.
| Champ | Valeur |
|---|---|
| URL de base | https://api.nanobananaapis.com/v1 |
| Clé API | Votre clé, envoyée en tant que Authorization: Bearer <key> |
| ID du modèle | uncensored |
Une remarque préalable à vos débuts. Il s'agit d'un modèle de langage textuel, donc il ne fonctionnera pas aux endroits qui attendent de la génération d'images, de la parole ou des embeddings. Les méthodes prises en charge sont POST /v1/chat/completions et GET /v1/models. Si un outil demande un modèle d'embedding pour la recherche, pointez cette partie vers un autre fournisseur.
Vous obtenez une clé depuis la page clé API. Les nouveaux comptes peuvent réclamer 0,50 $ de crédit d'essai gratuit en un clic, sans carte, valable 7 jours.
Testez l'endpoint avant de toucher à un outil
Quand une intégration échoue, on blâme l'outil. La plupart du temps, la clé ou l'URL est incorrecte. Un test curl de trente secondes lève ce doute. Listez d'abord les modèles :
curl https://api.nanobananaapis.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
Ensuite, envoyez une courte requête de 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}'
Si les deux fonctionnent, l'endpoint et la clé sont valides, et toute erreur ultérieure vient de la configuration de l'outil. Si le premier appel renvoie 401, la clé est incorrecte ou il manque le mot Bearer dans l'en-tête. Un 404 signifie généralement que l'URL manque de /v1 ou contient un chemin en double.
SillyTavern
SillyTavern est une interface pour le jeu de rôle et le chat de personnages, et elle permet d'ajouter un endpoint compatible OpenAI. Les libellés du menu changent entre les versions, considérez donc les étapes comme une carte plutôt que comme des libellés exacts.
- Ouvrez le panneau de connexion API et choisissez Chat Completion comme type d'API.
- Sélectionnez la source Custom (OpenAI-compatible).
- Collez
https://api.nanobananaapis.com/v1comme URL de l'endpoint. - Collez votre clé dans le champ clé.
- Saisissez
uncensoredcomme nom de modèle, ou appuyez sur le bouton connect et sélectionnez-le dans la liste retournée parGET /v1/models. - Appuyez sur connect et envoyez un message de test.
Deux remarques sur le réglage. SillyTavern envoie de longs historiques avec des cartes de personnage, alors surveillez la fenêtre de contexte de 100 000 tokens, partagée entre le prompt et la réponse. Et si vous utilisez des chats de groupe qui déclenchent plusieurs requêtes à la fois, rappelez-vous la limite de 8 requêtes simultanées avec une clé complète (2 sur une clé d'essai). Les configurations de jeu de rôle et d'accompagnement sont pour les adultes ; le modèle ne produira pas de contenu sexuel impliquant des mineurs, quel que soit le prompt.
LangChain
En Python, le package langchain-openai fournit ChatOpenAI, qui accepte une URL de base personnalisée. Installez-le avec 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)
Les chaînes, les modèles de prompt et les analyseurs de sortie fonctionnent de la même manière ensuite, car ils ne se soucient que de l'interface de chat. L'appel d'outils passe par le chemin standard, donc llm.bind_tools([...]) envoie tools dans la requête. Testez un appel d'outil unique avant de construire un agent autour, et limitez le parallélisme de l'agent à 8. Un graphe qui se divise en vingt branches déclenchera l'erreur concurrency.
Le package JavaScript @langchain/openai reprend la même idée via une option configuration: { baseURL } sur ChatOpenAI.
Cursor et autres éditeurs
Cursor, comme plusieurs autres éditeurs de code, dispose d'une zone de paramètres pour les modèles où vous pouvez fournir votre propre clé API OpenAI et remplacer l'URL de base. En gros : ouvrez les paramètres du modèle, activez l'option clé OpenAI personnalisée, définissez l'URL de base de remplacement sur https://api.nanobananaapis.com/v1, collez votre clé, et ajoutez uncensored comme nom de modèle personnalisé.
Soyez réaliste sur ce que cela vous offre. Les éditeurs construisent certaines fonctionnalités, comme la complétion en ligne, autour de leurs propres serveurs et noms de modèles spécifiques, donc un endpoint personnalisé ne s'appliquera peut-être qu'au chat ou à un sous-ensemble de commandes. Les options exactes changent entre les versions, alors consultez la documentation actuelle de l'éditeur. Si une fonctionnalité nécessite quelque chose que cette API n'offre pas, comme des embeddings ou des images en entrée, cela ne fonctionnera pas via cet endpoint.
Le même schéma s'applique aux autres clients compatibles OpenAI tels qu'Open WebUI, Continue et des interfaces de chat similaires : trouvez le champ pour un endpoint OpenAI personnalisé, saisissez les trois valeurs, et testez.
SDK bruts et variables d'environnement
Si vous écrivez votre propre code, les SDK officiels lisent les variables d'environnement standard, ce qui vous permet de changer d'endpoint sans toucher aux fichiers source. Dans les SDK Python et Node, définir OPENAI_BASE_URL et OPENAI_API_KEY suffit.
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 explicite en Node ressemble à ceci :
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 ?? "");
}
Le streaming arrive via SSE avec l'utilisation rapportée à la fin. Les détails complets des paramètres sont sur la page de documentation, et l'article sur la génération de prompts montre comment connecter une étape textuelle à un pipeline d'images.
Correction des échecs courants
| Symptôme | Cause probable | Correction |
|---|---|---|
| 401 Non autorisé | Clé incorrecte, ou en-tête manquant Bearer | Recopiez la clé et testez avec curl |
| 404 Non trouvé | URL de base sans /v1, ou chemin en double | Utilisez exactement https://api.nanobananaapis.com/v1 |
| Modèle non trouvé | L'outil utilise par défaut un nom de modèle de fournisseur | Définissez le modèle sur uncensored |
429 avec rate_limited | Plus de 300 requêtes par minute (60 par minute en essai) | Ralentissez et réessayez |
429 avec concurrency | Plus de 8 requêtes simultanées (2 en essai) | Réduisez le parallélisme |
| 429 avec Retry-After: 5 | Surcharge temporaire | Attendez cinq secondes puis réessayez |
| Requête trop volumineuse | Corps supérieur à 8 Mo | Réduisez les pièces jointes ou l'historique |
Gardez à l’esprit qu’une requête en flux occupe son slot de concurrence jusqu’à la fin du flux ; un éditeur qui abandonne les flux peut donc sembler atteindre la limite alors qu’il n’est pas occupé. Enregistrez l’en-tête X-Request-Id des appels échoués ; c’est la première chose que le support vous demandera.
Pour une conversation typique de 2 000 tokens en entrée et 500 en sortie, le coût est de 0,00055 $ aux tarifs de 0,15 $ et 0,50 $ par 1 M de tokens, et les requêtes échouées ne sont pas facturées. La page tarification couvre les recharges de 20 $ à 500 $ et les paliers de bonus.
Clés, sécurité et visibilité des données
Chaque intégration stocke votre clé quelque part, et certaines le font mieux que d’autres. Dans une interface de bureau, la clé est conservée dans un fichier de paramètres local. Dans un outil basé sur un navigateur, elle peut être sauvegardée dans le navigateur. Dans un éditeur, elle réside dans la configuration de l’application. Sachez laquelle vous utilisez avant de partager votre écran, de valider un fichier de configuration ou de confier votre ordinateur portable à quelqu’un d’autre.
Quelques règles rendent cela gérable. Utilisez une clé par outil si possible, afin de pouvoir remplacer une seule clé sans tout casser. Ne collez jamais une clé dans un gestionnaire de problèmes public lorsque vous demandez de l’aide ; partagez plutôt l’ID de requête. Si une clé fuit, remplacez-la depuis la page clé et mettez à jour vos outils. Les prompts envoyés via l’API ne sont pas utilisés pour l’entraînement, et la page confidentialité décrit le reste du traitement des données.
Si vous hébergez une interface pour d’autres personnes, ne livrez pas votre clé au navigateur. Placez un petit serveur entre vos utilisateurs et l’API, ajoutez vos propres limites à cet endroit, et conservez la clé sur le serveur. Vos utilisateurs partagent alors vos 8 requêtes simultanées ; prévoyez donc combien de personnes peuvent discuter en même temps.
Quel outil convient à quel usage
L’intégration étant la même partout, le choix de l’outil dépend de ce que vous créez.
- SillyTavern ou une interface de chat similaire convient pour le chat de personnages, la fiction et le jeu de rôle pour adultes, où vous souhaitez une interface soignée et des cartes de personnages sans écrire de code.
- LangChain convient aux pipelines dans le code : chargeurs, modèles de prompt, analyseurs et chaînes multi-étapes. Il ajoute de la structure au prix d’une dépendance supplémentaire.
- Un appel SDK simple convient aux petits scripts et services. Si votre tâche consiste en un prompt en entrée et une réponse en sortie, la bibliothèque OpenAI seule est moins à maintenir qu’un framework.
- Un éditeur comme Cursor convient pour discuter de code. Vérifiez lesquelles de ses fonctionnalités acceptent un point de terminaison personnalisé avant de vous y fier.
Commencez par le test curl brut, puis le SDK, puis ajoutez un framework uniquement lorsque vous en ressentez le besoin. Passer à un framework plus tard est facile, car les trois valeurs ne changent jamais. Pour une première requête et la liste complète des paramètres, consultez la documentation.
