Guide de l'API Nano Banana : appeler nano-banana, nano-banana-2 et nano-banana-pro sur HiAPI

Ce que propose la famille de modèles Nano Banana

La génération d'images ne se limite rarement à un seul réglage. En début de projet, vous avez besoin de brouillons rapides pour explorer des idées ; plus tard, vous avez besoin de rendus soignés pour livrer. La famille Nano Banana sur HiAPI est justement construite autour de cette réalité : une seule interface, trois variantes, chacune ajustée à un point différent de la courbe qualité/vitesse.

Le nommage est intentionnel. nano-banana est l'option de base — utilisez-la lorsque vous façonnez encore un prompt ou une mise en page et avez besoin d'un retour visuel rapide. nano-banana-2 va plus loin en fidélité et en respect du prompt ; c'est généralement le choix lorsque la sortie est proche du résultat final mais que vous voulez continuer à itérer. nano-banana-pro est la variante la plus fidèle de la famille, adaptée aux rendus finaux où les détails et la composition comptent le plus.

Ce qu'elles partagent compte autant que ce qui les distingue. Les trois s'appellent via le même point de terminaison HiAPI. Vous vous authentifiez une fois, construisez une requête une fois, et ne changez que l'identifiant du modèle lors du basculement. Cela signifie qu'une application peut lancer une requête sur le modèle de base, puis relancer le même prompt sur une variante plus puissante sans toucher au code de la couche de transport.

Une telle famille simplifie aussi votre architecture. Au lieu d'intégrer un fournisseur distinct pour chaque niveau de qualité, vous conservez un seul client, un seul chemin de gestion des erreurs et un seul point d'observation de l'usage. Le choix du modèle devient un paramètre, pas une intégration.

Pourquoi une famille plutôt qu'un modèle unique

Les différentes étapes d'un flux de travail ont des besoins différents. L'exploration de prompts, les brouillons de mise en page et les aperçus client privilégient la vitesse ; les visuels principaux et les supports marketing privilégient la fidélité. Traiter le choix du modèle comme une décision d'exécution vous permet d'associer chaque étape à la variante appropriée sans reconstruire le pipeline.

Choisir entre nano-banana, nano-banana-2 et nano-banana-pro

Choisissez une variante en vous posant deux questions : à quel point cette sortie est-elle proche de la version finale, et combien d'essais faudra-t-il pour y arriver ? Le reste en découle.

nano-banana : pour le volume et l'exploration

Utilisez le modèle de base tant que vous décidez encore de l'apparence que devrait avoir l'image. La reformulation de prompts, les tests de style et les vignettes de mise en page bénéficient tous d'un cycle rapide, et un rendu approximatif répond souvent mieux à votre question qu'une description. Gardez-le comme option par défaut pendant le développement.

nano-banana-2 : pour les itérations proches du final

Passez à nano-banana-2 lorsque la composition est stable et que vous affinez les détails — espacement, fidélité du sujet, degré de respect du prompt par la sortie. C'est le compromis pragmatique : un respect nettement plus fort sans passer par le chemin de plus haute fidélité à chaque aperçu.

nano-banana-pro : pour le rendu final

Réservez nano-banana-pro aux sorties à livrer. Les visuels principaux, les images produit et tout contenu que le client examinera attentivement méritent la variante la plus puissante. Ne la définissez pas par défaut — gardez-la pour la dernière étape, afin que vos itérations exploratoires restent peu coûteuses.

Une règle de routage pratique

Une stratégie d'escalade simple convient à la plupart des équipes :

• Utilisez nano-banana par défaut pour tous les nouveaux prompts.
• Faites monter le prompt vers nano-banana-2 lorsque la structure est correcte mais que la qualité ne suffit pas.
• Une fois le prompt verrouillé, exécutez la version finale une fois sur nano-banana-pro.

Cela rend l'itération rapide et prévisible, et rend vos schémas d'usage faciles à comprendre. La facturation suit l'usage et varie selon la variante ; vérifiez donc les tarifs et limites actuels dans la documentation du modèle en direct plutôt que de coder en dur un chiffre quelconque.

Schémas de prompts communs à toutes les variantes

La chose la plus coûteuse que vous puissiez faire est d'écrire des prompts qui ne fonctionnent que sur un seul modèle. Structurez-les pour qu'un changement d'une ligne suffise à basculer.

Le prompt en quatre blocs

Rédigez chaque prompt en quatre parties étiquetées, dans cet ordre :

1. Sujet — ce que contient l'image, énoncé simplement.
2. Style — le traitement visuel : photo, illustration, aquarelle, rendu 3D.
3. Composition — cadrage, angle de caméra, position, espace négatif.
4. Contraintes — ce qu'il faut éviter et toute exigence impérative.

Un exemple rempli :

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

Comme les blocs sont indépendants, vous pouvez renforcer le style ou assouplir la composition sans réécrire tout le prompt — et la même structure est facilement comprise par chaque variante de la famille.

Rendre les prompts indépendants du modèle

Évitez les formulations qui présupposent une caractéristique d'un modèle particulier. Décrivez le résultat souhaité, pas les étapes qu'un modèle spécifique devrait suivre. Lorsque vous devez comparer des variantes, ne changez que l'ID du modèle et gardez le prompt identique octet pour octet, afin que la comparaison ait du sens.

Versionner les prompts comme du code

Stockez les prompts sous forme de chaînes dans un fichier de configuration ou une petite bibliothèque de prompts, indexés par nom et version. Lorsqu'une variante produit une meilleure sortie grâce à un ajustement fin, consignez ce changement. C'est précisément ce qui permet à un prompt de migrer de nano-banana à nano-banana-pro au moment de la livraison sans surprise.

Les contraintes négatives comptent

Si un prompt produit systématiquement du texte, des logos ou des objets non désirés, ajoutez-les explicitement au bloc de contraintes. D'une variante à l'autre, des contraintes négatives claires sont souvent plus fiables qu'une formulation astucieuse.

Construire des requêtes fonctionnelles sur HiAPI

Chaque variante s'appelle via le même point de terminaison HiAPI. Une requête comporte quatre parties variables : l'URL de base, l'en-tête d'authentification, le champ modèle et la charge utile.

La forme de la requête

Un appel minimal de génération d'image ressemble à ceci :

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
  }'

Conservez la clé API dans une variable d'environnement ou un gestionnaire de secrets — jamais dans le code source. Le champ model est le seul à modifier pour changer de variante, et le champ prompt porte la structure en quatre blocs de la section précédente.

En Python, le même appel ne demande que quelques lignes :

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()

Ce que contient la réponse

La réponse transporte le résultat de l'image — généralement une URL ou une charge utile encodée — ainsi que des métadonnées identifiant le modèle qui a traité la requête. Relisez le champ modèle et consignez-le : c'est le moyen le moins coûteux de savoir après coup quelle variante a généré un asset donné.

Confirmer les paramètres avant de livrer

L'ensemble exact des paramètres optionnels varie selon la variante et évolue avec le temps. Avant de coder en dur quoi que ce soit en dehors de model et prompt, consultez la documentation du modèle en direct pour connaître les noms de champs et valeurs acceptées actuels. Traitez tout ce qui n'est pas documenté comme non pris en charge, plutôt que de deviner.

Gérer les réponses, les échecs et les nouvelles tentatives

La génération d'images est un appel réseau avec un modèle derrière, alors prévoyez la partie qui peut échouer.

Valider avant de faire confiance

Après chaque réponse, vérifiez trois choses : le statut HTTP, la présence d'une charge utile d'image et si le modèle renvoyé correspond à celui demandé. Échouez explicitement en cas d'incohérence, plutôt que de propager un asset défectueux en aval.

Ne réessayer que les échecs qui le méritent

Toutes les erreurs ne méritent pas une nouvelle tentative. Un prompt mal formé ou un nom de modèle invalide échouera de la même manière à chaque fois — corrigez la requête. Les échecs transitoires comme les délais d'attente, les réinitialisations de connexion et les réponses de limitation de débit méritent une nouvelle tentative.

Utilisez un backoff exponentiel borné avec 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())

Limitez le nombre total de tentatives pour qu'une requête défectueuse ne boucle pas indéfiniment, et consignez le modèle et le hachage du prompt à chaque tentative afin de voir si une variante donnée est instable.

Basculer délibérément

Si une variante échoue de manière persistante, revenir à un autre membre de la famille maintient le pipeline en vie. Comme les trois partagent la forme de requête, le repli consiste simplement à utiliser une valeur model différente lors de la nouvelle tentative. Décidez de l'ordre à l'avance — par exemple, revenir de nano-banana-pro à nano-banana-2 lorsque les appels à haute fidélité échouent à plusieurs reprises — et consignez le moment où le repli se déclenche afin de repérer les schémas.

Rendre les échecs visibles

Validez la charge utile renvoyée avant de la stocker, et émettez des métriques sur les nouvelles tentatives et les replis. Lorsque le taux d'erreur augmente, vous voulez le savoir avant qu'un lot de tâches ne produise silencieusement des sorties vides.

Durcir avant de livrer

Avant d'exposer la génération d'images à vos utilisateurs, parcourez cette liste.

Confirmer les ID et les paramètres

Les identifiants de modèles changent. Revérifiez les noms de modèles actuels de la famille Nano Banana et confirmez chaque paramètre optionnel auprès de la documentation en direct. Ne livrez pas de valeurs qui n'existent que dans d'anciens exemples.

Centraliser la configuration

Placez les ID de modèles, les modèles de prompts et les limites de nouvelles tentatives dans un module de configuration unique. Lorsque vous faites évoluer un prompt de nano-banana à nano-banana-pro, cela doit être un changement de configuration, pas une modification de code dispersée dans plusieurs fichiers.

Consigner ce qui compte

Pour chaque appel, consignez le modèle, la version du prompt, le statut de la réponse, la latence, et si une nouvelle tentative ou un repli a eu lieu. Hachez les prompts longs pour garder les logs lisibles. C'est précisément ce qui permet de répondre à la question « pourquoi cette image est-elle différente hier ? ».

Surveiller l'usage à mesure que vous montez en charge

La facturation suivant l'usage, surveillez le nombre d'appels et la répartition des variantes. Un outil d'exploration qui bascule silencieusement vers nano-banana-pro à chaque requête peut devenir un problème de coût. Routez délibérément : variantes économiques pour l'itération, variantes plus puissantes pour les sorties finales.

Tester le point de terminaison

Écrivez un petit test de fumée qui appelle chaque variante une fois avec un prompt fixe et vérifie que la réponse est valide. Exécutez-le avant chaque publication contre la documentation actuelle, afin qu'un changement de modèle ne vous prenne jamais au dépourvu en production.

Livrée avec un client unique, une bibliothèque de prompts partagée et une stratégie de routage délibérée, la famille Nano Banana sur HiAPI devient la seule dépendance dont vous avez besoin pour passer du brouillon au rendu final sans réécrire l'intégration.