Blog

Tutoriel

Comment utiliser nano-banana-2 via l'API HiAPI : exemples curl et Python Requests fonctionnels

Un guide développeur pour intégrer nano-banana-2 dans votre pipeline de génération d'images

Nov 12, 2026
Image de couverture minimaliste : sur un fond sable chaud, des bandes en escalier horizontales couleur terre cuite et brun foncé sont décalées vers le bas comme dans un graphique à barres de mercure.
Sur cette page

Ce que nano-banana-2 peut faire pour vous, et quand l'utiliser

nano-banana-2 est un modèle de génération d'images accessible via une API HTTP. Vous envoyez un prompt, éventuellement accompagné d'une image source, et vous récupérez une image générée. C'est tout le modèle mental dont vous avez besoin avant d'écrire du code.

Vous devriez utiliser nano-banana-2 lorsque vous avez besoin de générer des images par programmation dans un produit ou un pipeline existant, plutôt que via une fenêtre de chat : génération de supports marketing, création de vignettes et de couvertures, modifications itératives à partir d'une image de base, ou tâches par lots où le nombre d'images est piloté par vos propres données. Comme son interface est une API classique de type requête/réponse, vous pouvez la placer derrière un worker de file d'attente, un point de terminaison backend ou un outil CLI, sans avoir à introduire un nouveau SDK pour chaque langage.

Deux modes couvrent la plupart des cas d'usage :

  • Texte-vers-image — vous décrivez ce que vous voulez avec un prompt, et vous obtenez une image.
  • Image-vers-image — vous fournissez une image source, plus un prompt décrivant la transformation, et vous récupérez l'image modifiée.

Les deux modes ont la même forme de requête, donc un seul encapsuleur client (que nous construirons plus loin dans cet article) peut gérer les deux. Si votre pipeline ne fait que rendre à partir de texte, vous pouvez ignorer complètement le champ image. Si votre pipeline concerne l'édition de supports existants, l'image-vers-image est votre point d'entrée.

Ce que nano-banana-2 ne fait pas à votre place : il ne gère pas vos nouvelles tentatives, vos délais d'expiration, votre stockage ou votre idempotence. Ce sont des éléments que vous construisez autour de l'appel — et c'est précisément l'objet de la majeure partie de ce tutoriel, car appeler naïvement requests.post dans une boucle est la cause la plus fréquente de « la démo fonctionne, pas la production ».

Avant d'envoyer votre première requête

Avant le premier appel, vous devez préparer trois choses.

1. Identifiants de la plateforme

Vous devez obtenir l'accès API depuis la plateforme HiAPI, ainsi que les identifiants attribués à votre compte. Traitez-les comme des secrets : chargez-les depuis des variables d'environnement ou un gestionnaire de secrets, ne les committez jamais dans un dépôt de code et ne les collez jamais dans un artefact de build client. Chaque requête ci-dessous lit la clé depuis une variable d'environnement, afin qu'aucune information sensible n'apparaisse dans le code source.

export HIAPI_API_KEY="your-key-here"

2. Environnement client

Avec curl, vous avez seulement besoin d'un shell capable d'exécuter curl — les exemples utilisent des arguments fournis par les builds standard. Avec Python, vous avez besoin de Python 3 et de la bibliothèque requests :

python3 -m venv .venv
source .venv/bin/activate
pip install requests

3. Un endroit où stocker les sorties

La génération d'images renvoie des données d'image — que ce soit en ligne dans la réponse ou sous forme de référence récupérable ultérieurement dépend de la forme de réponse renvoyée par votre compte. Décidez à l'avance si vous allez enregistrer les octets sur disque, les téléverser vers un stockage objet ou renvoyer une URL à l'appelant. Y réfléchir dès maintenant évite le moment classique « ça fonctionne dans le shell, mais je n'ai nulle part où mettre le fichier ».

Vous n'avez pas besoin d'estimer des quotas ou des prix pour commencer. Le principe général pour une première intégration est : envoyez la requête valide la plus minimale, confirmez que vous obtenez une réponse valide, puis ajoutez des paramètres. La section suivante fait exactement cela.

Une requête curl minimale fonctionnelle

Voici un appel texte-vers-image complet. Le point de terminaison, les en-têtes et le corps de requête sont les seules parties variables : le point de terminaison identifie le modèle et l'opération sur la plateforme HiAPI, les en-têtes portent vos identifiants, et le corps JSON porte la charge utile.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a minimalist isometric workspace, soft daylight, muted palette",
    "n": 1
  }'

Définissez HIAPI_BASE_URL sur l'adresse de base de l'API indiquée dans le tableau de bord de votre compte HiAPI, afin de ne pas coder en dur le nom d'hôte dans le script. Le corps de requête comporte trois champs, tous importants :

  • model indique à la plateforme quel modèle exécuter. Gardez-le explicite même si vous utilisez une valeur par défaut ailleurs ; cela permet aux journaux de parler d'eux-mêmes.
  • prompt est en langage naturel. Décrivez précisément le sujet, la composition et le style ; des prompts vagues produisent des images vagues.
  • n est le nombre d'images demandées pour ce prompt. Commencez par 1 lors de la vérification que la chaîne fonctionne.

Une réponse réussie renvoie les données d'image dans le corps de la réponse. Inspectez-la avant d'écrire le moindre parseur : passez la sortie dans jq ou redirigez-la vers un fichier, puis regardez les clés de premier niveau. Vous vérifiez deux choses — que la requête a été acceptée, et où se trouve réellement la charge utile de l'image dans la réponse.

Ne vous précipitez pas pour ajouter des paramètres lors du premier appel. Une base fonctionnelle que vous comprenez vaut mieux qu'un énorme corps de requête que vous avez copié. Une fois que cet appel renvoie une image, chaque section suivante en est une variante.

La même requête, écrite en Python

Portez l'appel curl vers Python, sans modifier la charge utile. Conserver une source unique de vérité (un dict) signifie que le corps de requête que vous avez validé dans le shell est celui que vous mettrez finalement en production.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
                   timeout: float = 60.0) -> dict:
    """Envoie une requête de génération texte-vers-image et renvoie la réponse JSON analysée."""
    payload = {"model": model, "prompt": prompt, "n": n}
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "a minimalist isometric workspace, soft daylight, muted palette"
    )
    print(result.keys())

Trois détails méritent d'être soulignés, car ce sont les parties que les gens oublient le plus souvent en copiant des extraits de code.

Définissez toujours un timeout. Sans cela, une connexion bloquée bloquera votre worker indéfiniment. La valeur ci-dessus n'est qu'un point de départ, pas une règle absolue — ajustez-la en fonction de la latence que vous observez réellement.

Utilisez json= plutôt que data=. Passer un dict à json définit correctement le type de contenu et sérialise ; passer une chaîne brute à data est précisément la cause des erreurs de format de corps de requête qui ressemblent à des pannes du modèle.

Appelez raise_for_status() avant d'analyser. Essayer d'analyser une réponse 4xx avec .json() en cherchant le champ image produit des erreurs en aval déroutantes. Exposez d'abord le code de statut HTTP.

Cette fonction est l'encapsuleur réutilisable mentionné plus haut. La section suivante étend sa charge utile, sans le remplacer.

Les charges utiles texte-vers-image et image-vers-image

La différence entre les deux modes tient à un seul endroit : si le corps de requête contient ou non une image source. Tout le reste — point de terminaison, en-tête d'authentification, nom du modèle — reste inchangé.

Texte-vers-image

{
  "model": "nano-banana-2",
  "prompt": "a minimalist isometric workspace, soft daylight",
  "n": 1
}

Image-vers-image

{
  "model": "nano-banana-2",
  "prompt": "same scene, but converted to a warm evening palette",
  "image": "<base64-encoded source image>",
  "n": 1
}

Le concept à intégrer : en mode image-vers-image, le prompt décrit la transformation, et non la scène finale décrite de zéro. « Convertir en une palette chaude de soirée » vaut mieux que redécrire toute l'image, car l'image source fournit déjà le contenu.

Deux remarques pratiques sur le champ image :

  • Encodez l'image source au format spécifié par la documentation de l'API pour ce champ, et maintenez la charge utile encodée bien en dessous de votre budget de taille de requête. Des entrées trop volumineuses sont l'une des principales causes de rejet de requête.
  • Si vous prévoyez d'accepter des téléversements utilisateurs, validez la taille et le format avant l'encodage. Échouer rapidement de votre côté est bien moins coûteux qu'un aller-retour se terminant en 4xx.

Ajoutez un paramètre image optionnel à l'encapsuleur Python, et une seule fonction sert les deux modes :

def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
    payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
    if image is not None:
        payload["image"] = image
    # ... même appel de requête que précédemment

Comme la branche n'est qu'un if, votre code appelant décide du mode, tandis que la couche de transport reste inchangée. C'est la récompense de conserver un encapsuleur unique.

Gérer les tâches asynchrones et les nouvelles tentatives

La génération d'images peut prendre plus de temps qu'un appel d'API JSON typique. Certaines réponses renvoient immédiatement l'image terminée ; d'autres renvoient une tâche que vous devez interroger pour obtenir le résultat. Même si votre premier appel réussi renvoie immédiatement, concevez pour le scénario d'interrogation — sinon, lorsqu'une génération prendra trop de temps, votre pipeline s'effondrera.

Un modèle robuste comporte trois parties : une boucle d'interrogation avec backoff, une date limite stricte, et une politique de nouvelles tentatives distinguant « pas encore prêt » de « échec ».

import time
import requests


def poll_job(job_id: str, base_url: str, api_key: str,
             initial_wait: float = 2.0, max_wait: float = 30.0,
             deadline: float = 300.0) -> dict:
    start = time.monotonic()
    wait = initial_wait
    while True:
        if time.monotonic() - start > deadline:
            raise TimeoutError(f"job {job_id} exceeded deadline")

        response = requests.get(
            f"{base_url}/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30.0,
        )
        response.raise_for_status()
        body = response.json()

        status = body.get("status")
        if status == "succeeded":
            return body
        if status == "failed":
            raise RuntimeError(f"job {job_id} failed: {body}")

        time.sleep(wait)
        wait = min(wait * 2, max_wait)

Le chemin de la tâche et le vocabulaire des statuts doivent correspondre à ce que spécifie la référence API de votre compte HiAPI — adaptez les clés ci-dessus à la forme correspondante, mais conservez la structure.

Règles pour le maintenir sain en production :

  • Backoff exponentiel avec plafond. Interroger toutes les 200 ms gaspille du quota et martèle le point de terminaison ; doubler le temps d'attente avec un plafond se stabilise autour du temps de complétion réel.
  • Limitez le nombre total de tentatives et le temps total. Le deadline n'est pas négociable. Une boucle non bornée, c'est attendre qu'un jour lent provoque une panne.
  • Ne réessayez que les erreurs réessayables. Les erreurs réseau transitoires et les réponses 5xx méritent une nouvelle tentative avec jitter ; les réponses 4xx non — renvoyer une charge utile mal formée ne fait que perdre du temps. Utilisez un petit nombre borné de tentatives (deux ou trois) et journalisez chacune.
  • Rendez les nouvelles tentatives sûres. Si votre point de terminaison de création de tâche accepte une clé d'idempotence, envoyez une clé stable pour chaque requête logique, afin qu'une soumission rejouée ne produise pas de générations en double.

Avec une date limite, un backoff et un nombre borné de tentatives, une génération lente devient un événement journalisé et traité, plutôt qu'un worker suspendu.

Déboguer les erreurs que vous rencontrerez réellement

Lorsqu'un appel échoue, lisez d'abord le code de statut brut et le corps complet de la réponse, avant de toucher au moindre paramètre du modèle. Le corps de la réponse indique généralement le problème. Deviner est plus lent que journaliser.

Échecs d'authentification

Un 401 ou 403 signifie presque toujours l'une des choses suivantes : clé manquante dans la variable d'environnement, en-tête mal formé, ou identifiants inactifs dans cet environnement. Vérifiez la valeur littérale de l'en-tête que vous envoyez réellement — un préfixe Bearer manquant, ou un retour à la ligne superflu introduit depuis la clé copiée, sont des causes fréquentes.

Erreurs de charge utile

Un 400 avec un message concernant le corps de requête signifie que le JSON lui-même est incorrect : prompt manquant, virgule superflue, data= au lieu de json= en Python, ou champ image mal encodé. Affichez une fois les octets exacts que vous envoyez, inspectez-les, puis supprimez l'affichage.

Entrée rejetée

Les requêtes image-vers-image qui échouent à la validation concernent généralement l'image d'entrée : trop volumineuse, format incorrect ou impossible à décoder. Validez la taille et l'encodage de votre côté avant l'envoi, et renvoyez une erreur claire à la personne qui fournit l'image, plutôt que de réessayer.

Délais d'expiration et 5xx

Ceux-ci appartiennent à la catégorie réessayable. Distinguez dans les journaux les délais de connexion des erreurs serveur, et confirmez que vos nouvelles tentatives sont bornées — sinon un 5xx persistant devient une boucle infinie.

Un ordre de diagnostic efficace

  1. Journalisez le code de statut HTTP et le texte brut de la réponse pour chaque échec.
  2. Vérifiez d'abord le chemin des identifiants, avant tout le reste.
  3. Rejouez la charge utile échouée avec curl, en retirant votre code client de l'équation.
  4. Seulement après cela, ajustez prompt, image ou d'autres paramètres du modèle.

Si l'échec persiste après ces quatre étapes, capturez l'ID de requête (ou le champ de corrélation équivalent) depuis la réponse et joignez-le lorsque vous contactez le support — cela transforme un rapport vague en quelque chose de traçable.

Le rendre prêt pour la production

Avant la mise en ligne, parcourez cette liste de vérification.

  • Secrets : la clé API est chargée depuis des variables d'environnement ou un gestionnaire de secrets, et n'apparaît dans aucun journal, message d'erreur ni artefact de build client.
  • Délais d'expiration : chaque appel HTTP — création, interrogation et récupération de l'image résultat — a un délai d'expiration explicite.
  • Bornes : l'interrogation a une date limite, les nouvelles tentatives ont un nombre maximal de tentatives, et le code distingue les échecs réessayables des non réessayables.
  • Observabilité : journalisez pour chaque appel la forme de la requête (omise ou hachée si le prompt peut contenir des données utilisateur), le code de statut, la latence et l'ID de corrélation.
  • Conscience des coûts : la facturation suit les dimensions définies par votre compte HiAPI, donc suivez le nombre de générations et de sorties produites par requête, et instrumentez vos propres compteurs d'usage afin qu'une boucle incontrôlée soit visible avant la facture.
  • Stockage : les images générées sont écrites dans un emplacement persistant — stockage objet ou base de données — et non laissées dans un répertoire temporaire qui disparaît avec le conteneur.

Aucun de ces éléments n'est spécifique à nano-banana-2. C'est précisément le point : l'appel au modèle est la partie simple, et tout ce qui l'entoure relève de l'hygiène normale des systèmes distribués. Construisez un encapsuleur une fois, conservez la charge utile dans un seul dict, et le texte-vers-image comme l'image-vers-image en bénéficient gratuitement.

Commencez par l'appel curl, portez-le vers l'encapsuleur Python, ajoutez la boucle d'interrogation, puis parcourez la liste de vérification. Pour les détails du modèle et la dernière référence API, consultez la documentation de nano-banana-2 sur la plateforme HiAPI.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API