Blog

Tutoriel

Comment utiliser Nano-Banana via l'API HiAPI : curl, Python et requêtes exécutables

Nov 12, 2026
Plans de verre translucide superposés et abstraits, réfractant un fond gris clair en bandes d'un bleu froid, utilisés comme image de couverture de tutoriel
Sur cette page

Ce que Nano-Banana en tant qu'API offre aux développeurs

Nano-Banana est un modèle de génération d'images exposé via l'API HiAPI. Vous envoyez un prompt — et si nécessaire, une ou plusieurs images de référence — puis vous recevez l'image générée. Le modèle mental est aussi simple que cela. Pas besoin d'héberger le modèle localement, pas de GPU à préparer, pas de SDK supplémentaire à apprendre : le mode d'authentification, l'encapsulation des requêtes et le mécanisme de tâches asynchrones que vous utilisez avec les autres modèles HiAPI s'appliquent ici de la même manière.

Avant d'écrire du code, il est utile de clarifier ce que l'endpoint de génération d'images est et n'est pas. C'est un endpoint créatif : un même prompt peut produire des résultats différents d'une exécution à l'autre, et vous devez concevoir votre pipeline pour tolérer cela. Ce n'est pas une transformation déterministe comme le redimensionnement ou la conversion de format. Si vous avez besoin d'une reproductibilité au pixel près, mettez en cache les sorties que vous avez validées plutôt que de supposer qu'une régénération donnera le même résultat.

Une intégration typique se déroule en trois phases :

  1. Soumettre une requête de génération avec un prompt et toute entrée optionnelle.
  2. Attendre que la tâche de génération se termine, car la génération d'images prend plus de temps qu'une simple complétion de texte.
  3. Récupérer la sortie, la stocker, et décider si vous l'acceptez ou si vous ajustez le prompt et réessayez.

Deux choses méritent d'être décidées dès le départ, car elles influencent tout le reste : votre prompt est-il du texte pur ou utilise-t-il des images de référence (ce qui change la charge utile de la requête), et avez-vous besoin de maintenir la cohérence d'un personnage sur plusieurs générations (ce qui implique presque toujours l'utilisation d'images de référence). Les sections suivantes partent de la structure de la requête et s'étendent vers l'extérieur ; vous pourrez ajuster les exemples au fur et à mesure.

Anatomie d'une requête Nano-Banana

Chaque requête à Nano-Banana via HiAPI a la même ossature. Seule la charge utile change.

Endpoint et authentification

Les requêtes sont envoyées à l'URL de base de HiAPI, et le modèle spécifique est indiqué dans la charge utile de la requête, non dans une URL amont assemblée manuellement. Vous vous authentifiez en portant votre clé API dans l'en-tête Authorization. Conservez la clé dans une variable d'environnement — ne la mettez jamais en ligne dans le code source ni ne la commitez dans un dépôt.

Nom du modèle

L'identifiant du modèle est un champ de votre corps de requête JSON. Traitez-le comme une chaîne à copier textuellement depuis la liste des modèles, plutôt qu'à reconstruire vous-même, afin qu'un changement de nom ne casse pas silencieusement votre code.

Charge utile du prompt

Vous devez au minimum envoyer un prompt texte décrivant l'image cible. Ici, la qualité du prompt influence bien plus la qualité de la sortie que tout autre champ. Soyez précis sur le sujet, la composition, l'éclairage et le style. Un prompt vague génère une image vague, et aucun réglage de paramètre ne sauvera un prompt qui ne dit pas clairement ce que vous voulez réellement.

Images de référence optionnelles

Si vous incluez des images de référence, elles font partie du même corps de requête — généralement fournies sous forme d'URL d'image ou de données d'image encodées, selon le format accepté par le modèle. Les images de référence peuvent ancrer le visage d'un personnage, ses vêtements ou un style artistique global. Omettez-les pour une génération purement texte-vers-image ; incluez-les lorsque la sortie doit ressembler à un objet spécifique.

Champs liés à la sortie

Certains champs influencent la forme du résultat plutôt que son contenu : par exemple la taille de sortie ou le ratio d'aspect demandés. Il est préférable de les considérer comme des valeurs demandées plutôt que des garanties — la taille retournée par le modèle peut légèrement différer. Votre code en aval doit lire les dimensions réellement retournées plutôt que de supposer que vous obtenez ce que vous avez demandé.

Voici la structure conceptuelle, avec des valeurs d'espace réservé :

{
  "model": "<nano-banana-model-id>",
  "prompt": "Un renard roux assis dans des herbes hautes à l'heure dorée, faible profondeur de champ",
  "reference_images": [],
  "size": "1024x1024"
}

Consultez la documentation des paramètres du modèle pour connaître les noms de champs et formats exactement acceptés — la structure ci-dessus n'est qu'un schéma générique et ne remplace pas la documentation de référence.

Requête curl exécutable

Le moyen le plus rapide de vérifier que la clé fonctionne et que la charge utile est valide est un appel curl. Commencez par configurer l'environnement :

export HIAPI_API_KEY="your-api-key-here"

Puis soumettez la requête de génération :

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<nano-banana-model-id>",
    "prompt": "Un renard roux assis dans des herbes hautes à l'heure dorée, faible profondeur de champ",
    "size": "1024x1024"
  }'

Rôle de chaque partie :

  • URL — le chemin de génération d'images de HiAPI. Une URL de base sert tous les modèles ; le modèle est spécifié dans le corps de la requête.
  • Authorization — votre clé, lue depuis l'environnement pour qu'elle n'entre pas dans l'historique du shell ni dans la gestion de sources.
  • Content-Type — doit être application/json ; une erreur courante des débutants est de l'oublier, ce qui produit une erreur de parsing.
  • Corps de la requête — la charge utile JSON de la section précédente, contenant le prompt que vous voulez réellement.

Interpréter la réponse

La réponse vous indique ce qui s'est passé. Deux résultats méritent votre attention :

  • Résultat synchrone — certains appels retournent directement les données d'image ou une URL d'image. Si vous voyez une URL, récupérez-la et stockez-la rapidement, sans compter sur sa disponibilité à long terme.
  • Handle de tâche — si la génération est asynchrone, la réponse contient un identifiant pour interroger l'état. C'est le sujet de la section asynchrone ci-dessous.

Si vous voulez voir la ligne de statut HTTP et les en-têtes de réponse en plus du corps, ajoutez -i à la commande curl — en cas d'erreur, c'est très utile pour distinguer un problème d'authentification d'un problème de charge utile.

Le même appel en Python

Au-delà d'un script jetable, passez à Python. La bibliothèque requests permet de garder l'exemple léger en dépendances et de rendre la couche HTTP explicitement visible.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"

payload = {
    "model": "<nano-banana-model-id>",
    "prompt": "Un renard roux assis dans des herbes hautes à l'heure dorée, faible profondeur de champ",
    "size": "1024x1024",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

Quelques habitudes à prendre dès le départ :

  • Définissez un timeout. La génération d'images est lente ; sans timeout, votre worker peut rester bloqué indéfiniment. Pour les appels synchrones, un timeout assez large est un bon point de départ, mais ajustez-le selon votre charge.
  • Utilisez raise_for_status(). Cela convertit les réponses 4xx et 5xx en exceptions capturables, au lieu de parser silencieusement un corps d'erreur comme s'il s'agissait du résultat.
  • Encapsulez dans une fonction. L'extrait ci-dessus est un script ; dans un service, vous aurez besoin d'une fonction qui reçoit un prompt et retourne les données d'image ou un handle de tâche, afin que le reste de votre code n'ait pas à se soucier des détails HTTP.

Si la réponse contient une URL d'image, téléchargez et stockez-la immédiatement :

for item in data.get("data", []):
    url = item.get("url")
    if url:
        img = requests.get(url, timeout=60)
        img.raise_for_status()
        with open("output.png", "wb") as f:
            f.write(img.content)

La véritable source de données de votre application doit être votre propre stockage — pas une URL distante temporaire.

Gérer les tâches asynchrones

La génération d'images prend généralement plus de temps qu'un seul aller-retour HTTP ne devrait maintenir une connexion ouverte. Les modèles HiAPI qui fonctionnent ainsi retournent un identifiant de tâche lors de la soumission ; vous interrogez ensuite l'endpoint d'état de la tâche jusqu'à ce que le job soit terminé. Ce modèle s'applique à tous les modèles asynchrones de la plateforme, donc il suffit de l'apprendre une fois.

Soumettre d'abord, interroger ensuite

Votre POST initial retourne quelque chose comme un ID de tâche. Vous interrogez ensuite l'endpoint d'état avec cet ID. La logique dont vous avez besoin est :

import time

def poll_task(task_id, api_key, interval=2, max_wait=300):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"https://api.hiapi.ai/v1/tasks/{task_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        body = r.json()
        status = body.get("status")
        if status in ("succeeded", "completed", "failed", "error"):
            return body
        time.sleep(interval)
    raise TimeoutError(f"La tâche {task_id} ne s'est pas terminée dans les {max_wait} secondes")

Trois règles qui vous éviteront des pièges

  1. Limitez toujours le temps d'attente total. Un job qui ne se termine jamais ne doit pas bloquer votre worker. Le max_wait ci-dessus est votre porte de sortie.
  2. Backoff. Un intervalle court fixe convient à un usage interactif ; pour des jobs par lots, augmentez l'intervalle à mesure que l'attente s'allonge, afin de ne pas marteler l'endpoint d'état.
  3. Vérifiez l'état terminal. succeeded signifie que vous pouvez lire la sortie ; failed signifie que vous devez lire la charge utile d'erreur au lieu de réessayer aveuglément. Réessayer une charge utile mal formée ne fait que perdre du temps.

Persistez l'ID de tâche avec vos propres enregistrements de jobs. Si votre processus redémarre en cours de polling, vous pouvez reprendre le polling sans resoumettre et payer pour une génération en double.

Images de référence et cohérence des personnages

Les prompts purement textuels conviennent pour des images ponctuelles, mais ils montrent leurs limites lorsqu'il faut le même personnage dans dix scènes différentes. Décrire un visage en mots puis espérer que le modèle le reproduise de façon stable ne fonctionne presque jamais — de légères variations de formulation génèrent des personnes différentes.

Les images de référence résolvent ce problème. Vous incluez une ou plusieurs images dans la requête avec le prompt texte, et le modèle les utilise comme ancrage visuel. La cohérence des personnages est le cas d'usage central :

  • Fiche de personnage — une image de référence propre, plusieurs prompts de scène, visage et vêtements cohérents.
  • Ancrage de style — l'image de référence définit le langage visuel, le prompt guide le contenu.
  • Photos produit — l'image de référence d'un objet maintient son design stable sur différents arrière-plans.

Dans la requête, cela signifie remplir le champ des images de référence au lieu d'envoyer une valeur vide. Fournissez l'image sous forme d'URL ou de données encodées, selon ce que la spécification des paramètres du modèle prend en charge, et gardez l'image de référence propre : un sujet clair vaut mieux qu'une scène encombrée, car le modèle saisit tout ce qui est dans l'image, pas seulement ce qui vous intéresse.

Un schéma pratique pour le pipeline :

  1. Générez un personnage à partir d'un prompt texte détaillé.
  2. Examinez-le, acceptez ou régénérez jusqu'à satisfaction.
  3. Utilisez cette image validée comme image de référence pour chaque scène suivante.

C'est le workflow nano banana API python en résumé : verrouillez le personnage une fois, puis ne changez que la partie scène du prompt. Attendez-vous à itérer — les images de référence améliorent la cohérence mais ne la rendent pas parfaite, donc intégrez une étape de revue plutôt que de supposer que chaque sortie est utilisable.

Résolution de sortie et limites pratiques

La résolution est l'endroit où les hypothèses causent le plus facilement des problèmes, alors soyez prudent.

Taille demandée vs taille réelle

Vous pouvez demander une taille de sortie, mais considérez-la comme une indication. Le modèle peut retourner une taille différente de celle demandée — surtout pour des ratios d'aspect peu courants. L'approche robuste consiste à lire les dimensions de l'image réellement reçue et à traiter de façon générique : votre stockage, vos vignettes et votre mise en page doivent se baser sur le fichier réel, pas sur la valeur demandée.

Ce qui détermine la qualité

La qualité de sortie est principalement déterminée par le prompt, et le cas échéant par les images de référence. Un prompt bien composé, avec un sujet et un éclairage clairs, produit une meilleure image qu'un prompt vague mais avec une taille demandée plus grande. N'utilisez pas la résolution pour compenser un prompt insuffisamment descriptif.

Planifier autour des limites

  • Ne codez pas les dimensions en dur dans le code en aval. Lisez-les à partir de l'image retournée.
  • Validez avant de stocker. Si votre application exige une taille minimale, vérifiez les dimensions réelles après génération ; régénérez si elles sont insuffisantes — ne supposez pas que la demande a imposé cette exigence.
  • Attention à la taille des fichiers. Une sortie de résolution plus élevée implique des charges utiles plus grandes ; téléchargez en flux ou en tampon plutôt que de tout charger en mémoire dans une boucle.
  • Traitez par lots avec prudence. Les limites de concurrence sont par compte ; si vous générez beaucoup d'images, ajoutez un petit pool de workers avec des retries et backoff, plutôt que d'envoyer des requêtes en rafale dans une boucle non bornée.

Pour connaître les capacités faisant autorité et les valeurs acceptées de Nano-Banana, référez-vous à la documentation du modèle — pas aux charges utiles d'exemple de cet article. La facturation suit le mode normal de facturation à l'usage de la plateforme ; consultez le panneau de tarification pour les tarifs actuels, pas ce tutoriel.

Diagnostiquer les erreurs courantes

La plupart des échecs d'intégration initiale relèvent de quelques catégories. Voici les points à vérifier pour chacune.

401 / 403 — Authentification

Votre clé est manquante, mal formée ou non envoyée. Vérifiez que l'en-tête Authorization est présent, avec le préfixe Bearer , et que la variable d'environnement est bien exportée vers le shell ou le processus qui exécute le code. Un saut de ligne supplémentaire en fin de clé lors du copier-coller cause ce problème plus souvent que vous ne le pensez.

400 — Charge utile mal formée

Généralement l'un des cas suivants : JSON invalide (guillemets en trop ou virgule finale), Content-Type incorrect, champ requis manquant (comme prompt ou model), ou champ d'image de référence envoyé dans un format que le modèle n'accepte pas. Imprimez le corps exact que vous envoyez réellement et comparez-le champ par champ avec la spécification des paramètres.

404 — Chemin ou modèle incorrect

Le chemin de l'endpoint est erroné, ou l'identifiant du modèle ne correspond à aucun modèle de la plateforme. Copiez le nom du modèle textuellement depuis la liste, ne le tapez pas de mémoire.

Timeouts et polling bloqué

Pour les appels synchrones, un timeout trop court interrompt un job qui aurait pu réussir. Pour les jobs asynchrones, un polling bloqué signifie souvent que votre logique de polling sort trop tôt, ou que la vérification de l'état terminal ne correspond pas aux chaînes d'état réellement retournées par l'API — journalisez les valeurs d'état brutes et vérifiez. Conservez toujours un temps d'attente maximal, afin qu'un job bloqué échoue bruyamment plutôt que de rester suspendu.

Résultat vide

Un 200 sans image est presque toujours un problème de contenu plutôt qu'un bug : le prompt est peut-être trop vague, ou a peut-être été filtré. Avant de conclure à une erreur de l'API, vérifiez les champs d'erreur ou de raison dans le corps de la réponse, puis resserrez et clarifiez le prompt.

Échecs lors des retries

Si la même charge utile réussit parfois et échoue parfois, vous avez probablement atteint une limite de débit ou rencontré une erreur serveur transitoire. Ajoutez un backoff exponentiel autour de la soumission et du polling, et ne réessayez pas un 400 — corrigez la charge utile.

En cas de doute, le diagnostic le plus rapide est un appel curl minimal avec un prompt simple. S'il fonctionne, le problème vient de votre charge utile ou de votre code, pas des identifiants.

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