Comment utiliser l'API Nano Banana 2 Lite : curl, Python et une requête exécutable

Nano-Banana-2-Lite est le modèle économique de la famille de modèles d'image Nano-Banana sur hiapi : il utilise le même workflow basé sur des tâches que ses grands frères, à un prix par image plus bas, et prend en charge à la fois la génération texte-vers-image et l'édition à partir d'images de référence. Ce guide vous fait parcourir un flux d'intégration complet et exécutable — création d'une tâche, interrogation de la tâche, téléchargement du résultat — démontré en curl et en Python, et explique les détails de schéma qui le distinguent de Nano-Banana-2 et Nano-Banana-Pro.

Ce que vous allez construire, et ce dont vous avez besoin

Objectif : envoyer un prompt à Nano-Banana-2-Lite, attendre la génération de l'image, puis l'enregistrer sur le disque.

Vous n'avez besoin que d'une seule chose : une clé API hiapi (sk-...). Récupérez-la depuis votre tableau de bord hiapi. Le coût par image est indiqué sur la page de tarification et sur la page du modèle Nano Banana 2 Lite.

Tous les modèles d'image sur hiapi fonctionnent via l'API de tâches asynchrones unifiée : vous créez une tâche avec POST /v1/tasks, puis soit vous interrogez GET /v1/tasks/{id}, soit vous recevez un webhook lorsque la tâche est terminée.

Requête minimale exécutable (curl)

Créer la tâche :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
      "aspect_ratio": "3:2"
    }
  }'

L'identifiant de tâche renvoyé dans la réponse se trouve dans data.taskId. Interrogez-la :

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Lorsque data.status vaut "success", l'URL de l'image se trouve dans data.output[0].url. Téléchargez-la immédiatement — les URL de sortie sont signées et ont une date d'expiration (expireAt), donc enregistrez les octets, pas le lien.

Deux règles de schéma qui piègent facilement, directement issues de la validation de l'API elle-même :

• L'identifiant de modèle est sensible à la casse. "model": "nano-banana-2-lite" renvoie 400 MODEL_UNAVAILABLE ("model not available via /v1/tasks"). Utilisez l'identifiant exact Nano-Banana-2-Lite.
• prompt et aspect_ratio sont tous deux obligatoires. Omettre l'un ou l'autre entraîne un 400 INVALID_REQUEST avec le message missing required field. Valeurs valides de aspect_ratio : auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1.

Le même flux en Python

Aucun SDK nécessaire — l'API de tâches n'est que du JSON pur sur HTTPS :

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Create the task
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until the task reaches a terminal state
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Download immediately — output URLs are signed and expire
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

Édition avec images de référence : image_urls, pas image_input

Nano-Banana-2-Lite prend en charge l'édition d'images, mais son champ d'images de référence est image_urls — un tableau contenant jusqu'à 10 URL accessibles publiquement :

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "Replace the background with a clean white studio backdrop, keep the product unchanged",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

C'est le piège le plus fréquent de cette famille : Nano-Banana-2 et Nano-Banana-Pro utilisent image_input pour le même objectif, tandis que Lite refuse ce champ (additional properties 'image_input' not allowed). Des noms de champ comme input_urls, images ou reference_images sont rejetés sur les trois modèles. Si vous migrez du code d'un niveau à l'autre, le seul changement généralement nécessaire est ce renommage de champ.

Lite vs Nano-Banana-2 vs Pro : différences de schéma importantes

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
Entrées obligatoires	prompt, aspect_ratio	prompt	prompt
Images de référence	image_urls (≤10)	image_input	image_input
Contrôle de resolution	Non accepté	Accepté	Accepté

Lite garde une surface d'API minimale : prompt, ratio d'aspect, images de référence optionnelles. Pas de resolution, seed, n ni negative_prompt — envoyer l'un d'eux échoue à la validation avec additional properties ... not allowed. Si vous avez besoin d'un contrôle explicite de la résolution (1K/2K/4K) ou d'un niveau de fidélité supérieur, passez à Nano-Banana-2 ou Nano-Banana-Pro ; si vous générez en masse — vignettes, brouillons, boucles itératives, variantes en lot — le coût par image plus bas de Lite est précisément son intérêt.

Renforcer pour la production

Utilisez des webhooks plutôt que l'interrogation lorsque c'est possible. Ajoutez un bloc callback lors de la création de la tâche, et hiapi enverra le résultat final en POST à votre endpoint :

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when n'accepte que "final" — que ce soit un succès ou un échec, vous ne recevrez qu'un seul callback. L'interrogation convient aux scripts et aux notebooks ; les callbacks sont mieux adaptés aux serveurs car ils vous évitent de gérer des boucles d'interrogation et des délais d'attente. Si vous devez vraiment interroger, un intervalle de 2 à 5 secondes avec une échéance stricte (comme dans l'exemple Python) suffit.

Gérez les erreurs à deux niveaux. Les échecs au niveau de la requête sont renvoyés sous forme d'erreurs HTTP — une clé invalide ou non autorisée renvoie 401 avec {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}, et les erreurs de schéma renvoient 400 INVALID_REQUEST avec le message de validation précis. Les échecs au niveau de la tâche arrivent avec status: "fail" et un objet error sur la tâche elle-même ; gérez ces deux chemins dans votre code.

Rendez les nouvelles tentatives idempotentes. La création de tâche n'est pas idempotente — réessayer une requête de création expirée peut produire deux tâches (et deux facturations). Persistez le taskId dès sa réception, et après un redémarrage, continuez à interroger l'identifiant existant au lieu de recréer aveuglément.

Stockez les octets, pas les URL. Les URL de sortie expirent. Avant toute autre opération sur l'image, téléchargez-la et placez-la dans votre propre stockage.

Lectures complémentaires

• Page du modèle Nano Banana 2 Lite — paramètres, tarifs en temps réel, playground
• GPT Image 2 vs Nano Banana 2 : comparaison côte à côte avec le même prompt
• Maintenir la cohérence des personnages avec Nano-Banana sur hiapi
• Documentation hiapi et tarification

FAQ

Pourquoi ai-je reçu "model not available via /v1/tasks" ? L'identifiant de modèle est sensible à la casse. Utilisez exactement Nano-Banana-2-Lite ; les variantes en minuscules sont rejetées avec 400 MODEL_UNAVAILABLE.

Nano-Banana-2-Lite prend-il en charge l'édition image-vers-image ? Oui. Passez les images de référence dans le tableau image_urls (jusqu'à 10 URL). Il gère le remplacement d'arrière-plan, le transfert de style et les workflows d'édition par instructions pilotés par prompt.

Pourquoi mon code Nano-Banana-2 échoue-t-il sur Lite avec "additional properties 'image_input' not allowed" ? Les différents niveaux utilisent des noms de champ d'images de référence différents : Lite attend image_urls, tandis que Nano-Banana-2 et Pro attendent image_input. Renommez le champ lors du changement de niveau.

Puis-je définir resolution, seed ou le nombre d'images ? Pas sur Lite — son schéma d'entrée n'accepte que prompt, aspect_ratio et image_urls. Pour un contrôle de resolution 1K/2K/4K, utilisez Nano-Banana-2 ou Nano-Banana-Pro.

Combien de temps les URL des images de sortie sont-elles valides ? Ce sont des URL signées avec un horodatage d'expiration (expireAt dans l'objet de sortie). Téléchargez immédiatement les octets et stockez-les dans votre propre stockage ; ne faites jamais de hotlinking des sorties de tâches.

Que signifie 401 permission_denied ? Votre clé API est invalide, ou elle n'autorise pas l'utilisation de ce modèle. Vérifiez la clé dans votre tableau de bord et assurez-vous de l'envoyer sous la forme Authorization: Bearer sk-....

Combien coûte Nano-Banana-2-Lite par image ? Facturation à l'usage, par image, positionné comme le niveau le moins coûteux de la famille Nano-Banana. Consultez la page de tarification pour les tarifs actuels.