Comment utiliser Nano-Banana-2-Lite via l'API HiAPI : curl, Python et une requête fonctionnelle

Qu'est-ce que Nano-Banana-2-Lite et quand l'utiliser

Nano-Banana-2-Lite est le niveau ultra-économique de la famille Nano-Banana sur HiAPI. Il est destiné aux scénarios de génération d'images à forte concurrence et sensibles aux coûts, où vous privilégiez des dépenses prévisibles et une itération rapide plutôt que la fidélité maximale. Si vous prototypiez une fonctionnalité, générez des vignettes ou des variantes en lot, ou exécutez des tâches en arrière-plan qui peuvent tolérer un modèle plus léger, ce niveau est le bon point de départ.

Utilisez-le lorsque la sortie n'est qu'un maillon d'un pipeline plus vaste : visuels provisoires, images de remplacement, expérimentations en lot, ou tests A/B nécessitant un grand nombre de candidats à faible coût. Pour les visuels finaux principaux, ou les scénarios exigeant le plus de détails, passez à un niveau supérieur. L'interface de l'API reste inchangée, vous n'avez donc pas besoin de réécrire votre intégration pour changer de modèle.

Prérequis et structure de la requête

Avant d'appeler Nano-Banana-2-Lite, assurez-vous de disposer de :

• Un compte HiAPI et une clé API. Conservez-la dans une variable d'environnement, par exemple HIAPI_API_KEY ; ne la validez jamais dans un système de gestion de code source.
• Un terminal avec curl pour le premier test, ainsi que Python 3.8+ et la bibliothèque requests pour la version script.
• Un prompt décrivant l'image souhaitée. Commencez simple ; vous pourrez ajouter des entrées de référence ensuite.

Chaque requête vers HiAPI suit la même structure : un POST avec un corps JSON envoyé au point de terminaison du modèle. Le corps de la requête porte le nom du modèle, le prompt et tout paramètre optionnel. La génération étant asynchrone, l'appel de soumission renvoie un identifiant de tâche, que vous interrogez ensuite. La réponse est en JSON, et les erreurs incluent un code de statut et un message que vous pouvez journaliser.

Votre charge utile doit au minimum définir model sur nano-banana-2-lite et fournir un prompt. Les champs optionnels tels que reference_images et les paramètres de sortie sont présentés dans les sections suivantes.

Une requête curl fonctionnelle

Voici un exemple complet, directement copiable et exécutable, pour soumettre une tâche de base. Remplacez le prompt fictif par votre propre contenu.

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-lite",
    "prompt": "Un coin lecture douillet près d'une fenêtre sous la pluie, lumière chaude de lampe, mise au point douce",
    "aspect_ratio": "1:1"
  }'

La réponse contient l'id de la tâche et un champ status. Une tâche nouvellement soumise renvoie généralement queued ou processing. Conservez cet id ; vous l'utiliserez à l'étape d'interrogation. Si vous recevez 401, vérifiez que HIAPI_API_KEY est bien exportée dans votre shell. Si vous recevez 422, consultez le message d'erreur pour identifier le champ problématique.

Envoyer la même requête en Python

Portez l'appel curl en Python pour l'intégrer dans un script ou un service. Cet exemple utilise requests et lit la clé depuis les variables d'environnement.

import os
import requests

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

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "Un coin lecture douillet près d'une fenêtre sous la pluie, lumière chaude de lampe, mise au point douce",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

Conservez le corps de la requête dans un dictionnaire afin de pouvoir l'étendre avec des champs optionnels sans réécrire l'appel. Pour l'étape de soumission, un délai d'expiration de 30 secondes est raisonnable, car le gros du travail s'effectue de manière asynchrone.

Ajouter des entrées de référence optionnelles

Les entrées de référence vous permettent de guider la génération à l'aide d'un contexte visuel. Sur HiAPI, vous les ajoutez sous forme de tableau reference_images dans le même corps JSON. Chaque entrée est une URL accessible publiquement ou une URI de données base64. Utilisez des images de référence lorsque vous souhaitez préserver la composition, reproduire un style, ou maintenir la cohérence d'une image produit entre plusieurs variantes.

{
  "model": "nano-banana-2-lite",
  "prompt": "Même disposition, mais dans une palette de couleurs chaudes de coucher de soleil",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

N'incluez des images de référence que lorsqu'elles apportent un signal utile. Chaque référence représente des données supplémentaires à transmettre et peut diluer un prompt simple. Pour une tâche directe de texte-vers-image, omettez totalement ce champ. Lorsque vous utilisez des références, gardez-les pertinentes et peu nombreuses ; une ou deux images bien choisies surpassent généralement une grande collection.

Interroger les résultats asynchrones

La génération d'images est asynchrone : vous soumettez la tâche, puis interrogez le point de terminaison de la tâche jusqu'à ce que le statut devienne terminal. Le schéma est identique en curl et en Python.

Avec curl, vérifiez la tâche via son id :

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

En Python, encapsulez l'interrogation dans une boucle avec délai, afin de ne pas marteler l'API :

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

Commencez par un intervalle court, puis augmentez progressivement en cas d'interrogation de nombreuses tâches. Définissez toujours un nombre maximal de tentatives, afin qu'une tâche bloquée ne bloque pas indéfiniment votre processus de travail. Traitez failed comme un état terminal et journalisez le message d'erreur.

Télécharger et vérifier la sortie

Lorsque la tâche réussit, la réponse contient une ou plusieurs URL de sortie. Récupérez le fichier et enregistrez-le localement, puis vérifiez ce que vous avez obtenu.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

Effectuez des vérifications de base sur le contenu téléchargé : confirmez que le type de contenu est une image, vérifiez que la taille du fichier est non nulle et raisonnable, et ouvrez-la une fois pour confirmer qu'elle correspond à votre prompt. Enregistrez l'id de la tâche avec le nom du fichier local, afin de pouvoir retracer tout élément jusqu'à sa requête.

Liste de vérification des coûts et des pannes avant la mise en production

Nano-Banana-2-Lite est facturé au niveau ultra-économique ; la facturation suit la comptabilisation standard de la génération d'images de la plateforme. Consultez le panneau tarifaire actuel sur le site pour obtenir les tarifs exacts, plutôt que de coder en dur des hypothèses.

Avant la mise en ligne, adoptez les habitudes suivantes :

• Réessais avec repli exponentiel. Réessayez un petit nombre de fois en cas d'erreurs transitoires (délais d'expiration, 5xx) avec un délai croissant ; ne réessayez pas sur les erreurs de validation 4xx.
• Limiter l'interrogation. Utilisez un intervalle fixe et un nombre maximal de tentatives. Journalisez l'état final et la durée.
• Journaliser l'id de tâche et le prompt. Stockez l'id de tâche, le prompt, le modèle et toute entrée de référence avec chaque sortie, afin de pouvoir reproduire ou auditer les exécutions.
• Valider les entrées au plus tôt. Vérifiez la longueur du prompt et les URL de référence avant la soumission, pour éviter de gaspiller des tâches.

Avec ces vérifications, Nano-Banana-2-Lite est un outil de travail prévisible et économique pour la génération en lot et en arrière-plan. Parcourez la page du modèle sur HiAPI pour obtenir les paramètres et tarifs les plus récents.