Tutoriel
Tutoriel API Nano-Banana-2 : utiliser curl et Python Requests fonctionnels via hiapi
Sur cette page
Préparatifs avant le premier appel
Avant d'envoyer la moindre requête à Nano-Banana-2, préparez quatre éléments. Aucun ne prend beaucoup de temps, et une fois les quatre réunis, la première requête devient un simple copier-coller plutôt qu'une chasse au trésor.
1. Un compte hiapi et une clé API
Chaque requête est authentifiée par une clé API liée à votre compte hiapi. Créez la clé dans le tableau de bord de votre compte et conservez-la en lieu sûr — un gestionnaire de mots de passe, ou une variable d'environnement sur votre machine. Traitez-la comme un mot de passe : ne la validez jamais dans un dépôt de code et ne la collez pas dans des documents partagés.
Sur votre machine, exportez-la une fois par session de shell, afin que les exemples ci-dessous puissent la lire sans rien coder en dur :
export HIAPI_API_KEY="your_api_key_here"
2. L'URL de base de l'API
L'URL de base est l'adresse racine sur laquelle toutes les requêtes sont construites. Pour construire un point de terminaison, vous y ajoutez la route du modèle. Placez l'URL de base dans une variable de configuration de votre code, plutôt que de la disperser dans plusieurs fichiers — ainsi, si elle change, vous ne modifiez qu'une seule ligne.
3. Un client pour envoyer les requêtes
Pour commencer, vous n'avez besoin que de l'un des deux :
- curl — presque certainement déjà installé. Utilisez-le pour confirmer que votre clé et votre corps de requête sont corrects avant d'écrire le moindre code applicatif.
- Python 3 avec la bibliothèque
requests(pip install requests). La plupart des lecteurs l'utiliseront pour construire une véritable intégration.
Il est utile d'avoir les deux : curl isole la requête de votre code, donc en cas de problème, vous savez si le problème vient de l'appel API ou de l'application.
4. Savoir clairement ce que vous voulez générer
Nano-Banana-2 prend en charge à la fois la génération texte-vers-image et image-vers-image. Décidez à l'avance du mode dont vous avez besoin, car la structure du corps de requête diffère (détaillé plus loin). Pour le premier appel, commencez par le texte-vers-image — c'est celui qui comporte le moins de variables.
Clé exportée, client installé, prompt réfléchi : vous pouvez maintenant examiner la requête elle-même.
Les composantes d'une requête Nano-Banana-2
Un appel à Nano-Banana-2 est une requête POST avec un corps JSON. Chaque champ a son rôle ; les comprendre séparément signifie que, en cas de problème, vous pouvez modifier un seul aspect à la fois.
Le point de terminaison
La requête est envoyée à l'URL de base de l'API hiapi, à laquelle est ajoutée la route du modèle Nano-Banana-2. La méthode est toujours POST, car vous envoyez une charge utile à traiter, et non récupérez une ressource.
Les en-têtes
Deux en-têtes sont importants :
Content-Type: application/json— indique à l'API comment analyser votre corps de requête.Authorization— transporte votre clé API. Les exemples ci-dessous la lisent depuis la variable d'environnement que vous avez exportée précédemment.
Si l'un de ces en-têtes est absent ou mal formé, la requête échoue avant même que le modèle ne la voie. C'est la source unique la plus fréquente d'erreurs déroutantes.
Les champs du corps de requête
Une requête texte-vers-image comporte les champs suivants :
model— indique que le modèle à exécuter est Nano-Banana-2. Même s'il existe une valeur par défaut, indiquez-le explicitement ; cela rend votre code auto-documenté et vous protège si la valeur par défaut change.prompt— décrit en langage naturel l'image souhaitée. C'est ici que se déroulera l'essentiel de votre travail d'itération. Soyez précis : sujet, composition, style, lumière. Un prompt vague produit un résultat vague.- Entrée image — absente ou vide en texte-vers-image. En image-vers-image, elle transporte votre image de référence (voir la section image-vers-image pour plus de détails).
- Paramètres de sortie et de dimensions — champs propres au modèle qui influencent la forme ou le ratio du résultat renvoyé. Ne définissez que les champs indiqués comme pris en charge par la documentation du modèle ; dans une API stricte, les champs inconnus entraînent généralement un rejet de la requête plutôt qu'un ignoré silencieux.
Ce qui est renvoyé
La réponse est en JSON. Selon la façon dont l'appel est construit, vous recevrez directement les données de l'image générée ou une référence à celle-ci. Votre code client doit d'abord vérifier le statut HTTP, puis examiner le corps de la réponse — ne supposez pas qu'une réponse de forme 200 contient forcément une image sans le vérifier.
C'est toute la structure : une requête POST authentifiée avec un petit corps JSON explicite. Le reste de ce tutoriel n'est qu'une variation de cette forme.
Une requête curl fonctionnelle
C'est l'appel complet minimal que vous pouvez envoyer. Exécutez-le dans un terminal où la clé API a été exportée ; en quelques secondes, vous saurez si le compte, la clé et le chemin réseau fonctionnent tous correctement.
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
}'
Définissez une fois l'URL de base dans le shell, avec la clé :
export HIAPI_BASE_URL="https://api.hiapi.ai"
(Utilisez l'URL de base affichée dans votre tableau de bord hiapi — c'est la valeur de référence pour votre compte.)
Lire la sortie
curl affiche la réponse brute sur stdout. Si l'appel réussit, vous verrez du JSON contenant l'image générée. Faites passer le tout par python -m json.tool pour embellir la sortie et confirmer la structure :
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
| python -m json.tool
Interpréter ce que vous voyez
- Réponse réussie — confirme que votre clé est valide, que le point de terminaison est correct et que le corps de requête est analysable. Conservez cette commande qui fonctionne — c'est votre référence de base.
- Réponse d'erreur — indique qu'un élément des trois lignes d'en-tête ou du corps de requête est incorrect. Copiez le texte de l'erreur ; la section de débogage associe les erreurs courantes à leurs corrections.
L'intérêt de commencer par curl est l'isolement. Votre clé, vos en-têtes et votre JSON sont tous visibles au même endroit, de sorte qu'un échec pointe vers la requête elle-même, et non vers votre code applicatif. Une fois cette commande fonctionnelle, le portage vers Python devient mécanique.
La même requête en Python
Voici le même appel implémenté avec requests. Le corps de requête est exactement le même dict que celui du corps curl — rien ne change du côté de l'API, seule la façon de l'envoyer change.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Pourquoi l'écrire ainsi
json=payloaddemande àrequestsde sérialiser le dict pour vous et de définirContent-Type. Vous pouvez tout de même passer l'en-tête explicitement ; cela ne fait pas de mal et rend la requête auto-documentée.timeout=120— la génération d'image n'est pas instantanée. Un délai d'attente généreux empêche le client d'abandonner alors que le modèle travaille encore. Ajustez cette valeur selon votre cas d'usage.raise_for_status()transforme les réponses non 2xx en exceptions, afin que les échecs apparaissent immédiatement au lieu de s'infiltrer silencieusement dans votre code de traitement des résultats.- Les variables d'environnement éloignent la clé du code source. En production, injectez-la depuis le stockage de secrets de votre plateforme plutôt que d'utiliser un fichier
.envsusceptible d'être commité.
Extraire l'image
Le corps de la réponse est en JSON. Examinez-le une fois de manière interactive pour comprendre la structure exacte, puis extrayez explicitement le champ image :
image_url = data["image_url"] # confirm the key name against a real response
Si votre réponse contient des données base64 plutôt qu'une URL, décodez-les et écrivez-les :
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
Ne devinez pas les noms de champs — imprimez la réponse brute lors du premier appel réussi et extrayez les valeurs en fonction de ce qui est réellement présent. Cette seule habitude prévient la plupart des défauts d'intégration.
Texte-vers-image et image-vers-image avec image de référence
Jusqu'ici, il s'agissait de texte-vers-image : un prompt en entrée, une image en sortie. Nano-Banana-2 prend aussi en charge l'image-vers-image, où vous fournissez une image de référence que le modèle utilise comme guide. Savoir quand changer de mode et comment le corps de requête évolue fait la différence entre un appel réussi et un rejet.
Quand utiliser chaque mode
- Texte-vers-image — vous avez une idée exprimée en texte, sans image de départ. Idéal pour l'exploration, l'illustration et tout contenu généré à partir de zéro.
- Image-vers-image — vous avez une image existante et souhaitez une variante, une restylisation, ou une édition qui préserve sa structure ou son sujet. C'est le mode à utiliser pour itérer sur un design, assortir un style visuel ou transformer une photo.
Si votre prompt est du type « fais-le ressembler à… » ou « garde la mise en page mais… », vous avez besoin de l'image-vers-image.
Comment l'image de référence modifie la requête
Le point de terminaison et les en-têtes restent inchangés. Ce qui change, c'est le corps de requête : vous ajoutez un champ d'image de référence à côté du prompt. Selon la façon dont l'image est fournie, ce champ transporte une URL ou des données d'image encodées. Gardez ces règles en tête :
- Si vous transmettez un lien, utilisez une URL directement accessible publiquement. Les pages nécessitant une connexion ou une redirection authentifiée échouent — l'API a besoin de récupérer directement les octets.
- Respectez le format attendu. Les formats courants comme PNG et JPEG sont sûrs ; les fichiers exotiques ou corrompus sont une cause fréquente de rejet de requête.
- Vérifiez les limites de taille avant l'envoi. Les images volumineuses sont souvent la cause d'erreurs de corps de requête.
- Gardez un prompt ciblé. Avec une image de référence, décrivez la transformation souhaitée plutôt que de redécrire l'image de référence.
Voici un corps de requête image-vers-image à titre indicatif :
payload = {
"model": "nano-banana-2",
"prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
"image_url": "https://example.com/your-reference.jpg",
}
Comme toujours, confirmez le nom exact du champ à l'aide de votre première réponse réussie. Le principe est simple : en texte-vers-image, il n'y a que le prompt ; en image-vers-image, on ajoute une image de référence vérifiée sur la même forme de requête. Prouvez d'abord que le flux fonctionne en texte-vers-image, puis ajoutez l'image de référence.
Gérer les erreurs et déboguer les requêtes en échec
Les échecs d'appel à Nano-Banana-2 se répartissent en trois catégories. Apprendre à reconnaître chacune d'elles vous permet de corriger la plupart des problèmes en moins d'une minute.
Erreurs d'authentification
Si vous voyez une erreur d'authentification, cela signifie que la clé n'atteint pas correctement l'API. Vérifiez dans l'ordre :
HIAPI_API_KEYest-elle bien exportée dans le shell ou l'environnement qui exécute la requête ? Lancezecho $HIAPI_API_KEYpour confirmer.- L'en-tête
Authorizationest-il présent et correctement formaté ? Le schéma et la clé comptent tous les deux. - La clé a-t-elle été révoquée ou renouvelée dans le tableau de bord ?
- Accédez-vous à la bonne URL de base pour votre compte ?
Un 401 ou un 403 signifie presque toujours l'un de ces quatre cas. La clé elle-même est rarement le problème — c'est généralement le chemin qui l'entoure qui l'est.
Corps de requête mal formé
Les erreurs de type 400 signifient généralement que l'API ne peut pas analyser ou valider votre corps de requête :
- JSON invalide — virgules superflues, guillemets simples au lieu de guillemets doubles, ou caractères non échappés. Faire passer la sortie par
python -m json.toolet construire le corps de requête dans le code plutôt qu'à la main aident tous deux. - Champs obligatoires manquants —
modeletpromptsont ceux que l'on oublie le plus souvent ; envoyez toujours les deux explicitement. - Champs inconnus ou non pris en charge — les API strictes rejettent les champs qu'elles ne reconnaissent pas. Supprimez tout élément superflu jusqu'à ce que la requête passe, puis rajoutez-les un par un.
- Types de valeurs incorrects — un nombre envoyé sous forme de chaîne, ou un tableau là où une valeur unique est attendue. Respectez strictement les types de la documentation.
Entrées d'image incorrectes
Cela ne concerne que l'image-vers-image, mais c'est le plus frustrant quand cela arrive : URL d'image nécessitant une authentification, URL derrière une redirection, URL renvoyant du HTML au lieu d'une image, taille excessive ou format non pris en charge. Vérifiez que l'URL se charge directement dans un navigateur sans connexion, et contrôlez le type et la taille du fichier par rapport aux limites avant l'envoi.
Un ordre de débogage efficace
- Lisez littéralement le message d'erreur et le code de statut — ils pointent souvent le problème.
- Reproduisez la requête en échec avec un minimum de champs dans curl, puis rajoutez la complexité progressivement.
- Imprimez le corps complet de la réponse avant de le traiter ; ne vous fiez pas à vos suppositions sur sa structure.
Si un appel curl minimal réussit alors que votre application échoue, le défaut est dans votre code, pas dans l'API. C'est la frontière de diagnostic la plus rapide que vous puissiez établir.
Intégrer cela dans votre application
Une requête fonctionnelle est un bon début ; une intégration fiable nécessite quelques éléments autour. Voici comment passer d'un appel ponctuel à quelque chose sur lequel vous pouvez compter.
Envelopper l'appel dans une fonction
Isolez la requête dans une fonction qui prend un prompt (et éventuellement une image de référence) et renvoie le résultat. Placez la construction des en-têtes, de l'URL de base et du corps de requête à l'intérieur de cette fonction, afin que le reste de la base de code n'y touche jamais. Lorsque l'API change, vous ne modifiez qu'un seul endroit.
Gérer les tentatives avec discernement
La génération peut échouer temporairement pour des raisons indépendantes de votre corps de requête. Réessayez avec un backoff exponentiel, mais uniquement pour les échecs réessayables — délais d'attente et certaines erreurs côté serveur. Ne réessayez jamais les erreurs d'authentification ou de validation du corps de requête ; elles échoueront de la même manière à chaque fois et ne feront qu'ajouter de la charge. Limitez le nombre de tentatives pour que les problèmes persistants se révèlent au lieu de rester bloqués.
Délais d'attente et concurrence
Définissez un délai d'attente suffisamment généreux pour la génération mais borné, et ajustez-le après avoir mesuré les temps de réponse réels. Si vous envoyez beaucoup de requêtes, respectez une limite de concurrence raisonnable plutôt que de tout envoyer d'un coup — une file d'attente avec un pool de workers est plus prévisible que des appels parallèles illimités.
Stockez ce que vous générez
La réponse vous fournit l'image générée. Copiez-la rapidement dans votre propre stockage au lieu de compter sur la validité indéfinie de l'URL renvoyée. Nommez les fichiers de manière déterministe et consignez le prompt et les paramètres à côté de chaque sortie — vous aurez besoin de cette traçabilité lorsque vous itérerez plus tard sur les prompts.
Gardez les clés hors du code
Lisez la clé API depuis des variables d'environnement ou un gestionnaire de secrets dans chaque environnement. Renouvelez régulièrement les clés. Si une clé apparaît là où elle ne devrait pas, révoquez-la dans le tableau de bord.
Commencez petit, puis étendez
Faites fonctionner un prompt dans curl, portez-le en Python, ajoutez la gestion des erreurs de la section précédente, puis seulement construisez la file d'attente et le stockage environnants. Chaque étape valide la précédente.
Avec un appel curl vérifié, un client Python équivalent et les trois catégories d'erreurs maîtrisées, vous disposez du parcours complet, de la première requête à l'intégration en production.
Articles similaires
Voir tous les articles →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage