Guide de l'API Nano Banana : Génération et édition d'images sur TokenLab

L'API Nano Banana propose trois IDs de modèles payants sur TokenLab, et le moins cher coûte environ deux fois moins cher par image que le modèle intermédiaire. L'erreur coûteuse ne vient que rarement du choix du modèle. Elle consiste généralement à envoyer une requête d'édition au mauvais endpoint ou à relancer un appel de création qui a déjà généré une tâche. Ce guide couvre les IDs exacts, un appel text-to-image fonctionnel, un appel avec image de référence, le polling asynchrone, les erreurs attendues et la manière dont la facturation est définie. Les prix et les listes de champs ont été relevés le 03/10/2026 ; vérifiez-les donc à nouveau avant de passer en production.

Points clés

• Envoyez l'ID exact : nano-banana-2, nano-banana-2-lite ou nano-banana-pro. Les noms d'affichage ne sont pas des alias de requête.
• Le travail sur image de référence pour Nano Banana s'effectue via POST /v1/images/generations avec operation: "image-to-image" et image_urls. Il ne passe pas par /v1/images/edits ou /v1/chat/completions.
• Les prix de base relevés le 03/10/2026 sont de 0,0168 $, 0,0335 $ et 0,067 $ par image pour les IDs lite, standard et pro. Chaque modèle possède une fourchette de prix ; vérifiez donc le palier exact dans Usage.
• Une réponse de création contenant task_id, status: "pending" ou poll_url signifie que vous devez effectuer un polling sur GET /v1/tasks/{id} jusqu'à obtenir completed ou failed.
• Une lecture de statut renvoie un code HTTP 200 même si la tâche a échoué. Basez votre logique sur le champ status de la tâche, et non sur le code HTTP.
• Les frais finaux se trouvent dans Usage et dans billing_transaction_id, et non dans un tableau de prix copié.

Modèles de l'API Nano Banana, unités de prix et usages

En comparant le brouillon précédent de ce guide avec la documentation actuelle, nous avons identifié trois problèmes. Il listait des modèles sans prix. Il envoyait une édition Nano Banana via chat completions. Il interrogeait le catalogue avec un filtre que le guide des images n'utilise pas. Le tableau ci-dessous corrige le premier point. Les sections suivantes corrigent les deux autres.

ID du modèle	Idéal pour	Unité de tarification	Prix TokenLab (USD)	Source, observée
nano-banana-2	Text-to-image et image-to-image avec aspect_ratio et resolution (1k, 2k, 4k). Sorti le 26/02/2026.	per_image	0,0335 $ par requête. Fourchette de 0,0225 $ à 0,0755 $.	API du modèle en direct, 03/10/2026
nano-banana-2-lite	Text-to-image et image-to-image le moins cher. L'entrée de prix observée couvre le palier 1k.	per_image	0,0168 $ par requête. Min et max à 0,0168 $.	API du modèle en direct, 03/10/2026
nano-banana-pro	Text-to-image, image-to-image et édition d'image avec aspect_ratio et resolution.	per_image	0,067 $ par requête. Fourchette de 0,067 $ à 0,12 $.	API du modèle en direct, 03/10/2026
nano-banana	Text-to-image avec aspect_ratio uniquement. Pas de sélection de resolution publique.	Non documenté	Consultez la page du modèle ou l'endpoint de tarification	Catalogue, 02/10/2026 ; Docs Create Image, 03/10/2026

Tous les prix ci-dessus comportent is_lock_price: true et ont été mis à jour le 02/10/2026 à 16:53:30.068Z. Trois détails comptent avant de faire votre choix :

• Les paliers de résolution font varier le prix. L'API en direct affiche une fourchette pour nano-banana-2 et nano-banana-pro, mais nos données ne mappent pas chaque palier à une résolution. Ne supposez pas que 1k est le prix de base. Lisez les entrées de tarification pour votre modèle.
• La sortie texte a son propre prix par token. nano-banana-2 et nano-banana-pro comportent tous deux une entrée native-gemini-text-output. Elle s'applique lorsque outputModality est text. Pour nano-banana-2, elle liste 0,25 en entrée et 1,5 en sortie. Pour nano-banana-pro, elle liste 1 en entrée et 6 en sortie. L'unité est per_token. Confirmez l'échelle dans GET /v1/models/:model/pricing avant d'établir votre budget.
• Lite ne liste aucun format de requête accepté. L'enregistrement en direct pour nano-banana-2-lite indique "non listé". Lisez ses détails avant de développer avec.

Pour un budget approximatif, nous multiplions le prix de base par le volume. Ce sont des estimations basées sur le prix de base, pas des devis :

• 100 images sur nano-banana-2-lite : 100 × 0,0168 $ = 1,68 $.
• 100 images sur nano-banana-2 : 100 × 0,0335 $ = 3,35 $.
• 100 images sur nano-banana-pro : 100 × 0,067 $ = 6,70 $.

Les paliers de résolution plus élevés augmenteront ces chiffres.

Pour lister vous-même les modèles d'image actuels, appelez l'endpoint utilisé par le guide de génération d'images. Le brouillon précédent utilisait category=image, ce que le guide ne documente pas.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Pour les opérations, les prix et le cycle de vie d'un modèle, utilisez Get a Model. Vous pouvez également parcourir le répertoire des modèles TokenLab.

Envoyer une requête text-to-image avec l'API Nano Banana

Créez une clé API dans le tableau de bord TokenLab et exportez-la :

export TOKENLAB_API_KEY="your-tokenlab-api-key"

Envoyez toujours model. La référence Create Image indique que les API d'image ne choisissent pas de valeur par défaut. Un modèle manquant renvoie une erreur 400 avec param: "model".

Cette requête utilise uniquement les champs listés dans la documentation pour les familles d'images Google. Nous avons conservé resolution à 1k car nano-banana-2 documente 1k, 2k et 4k.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

Le flag --max-time 120 correspond à la documentation. Elle indique que les requêtes haute résolution peuvent prendre près d'une minute ou plus ; réglez donc votre timeout client sur au moins 120 secondes. La documentation indique que size est un alias de compatibilité pour les familles d'images Google, mais recommande d'utiliser directement aspect_ratio.

Un succès synchrone renvoie l'image terminée en ligne. Les valeurs fictives ci-dessous montrent uniquement la structure documentée :

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

Lisez-la dans cet ordre :

1. Si le corps contient task_id, status: "pending" ou poll_url, vous avez une tâche, pas une image. Allez à la section polling.
2. Sinon, lisez data[0].url. Avec response_format: "b64_json", lisez data[0].b64_json à la place.
3. created est un timestamp Unix. revised_prompt n'apparaît que lorsque le modèle en renvoie un ; ne l'exigez donc pas.
4. Stockez l'URL de l'image, votre propre ID de travail, le modèle et le request_id provenant des en-têtes de réponse.

Les URL des images générées peuvent être conservées comme copies média pendant 30 jours. Vérifiez media_retention.items pour le statut de chaque élément et expires_at. Les copies en attente ou échouées ne sont pas garanties ; copiez donc le fichier vers votre propre stockage si vous en avez besoin plus longtemps. Le guide de rétention des données contient les détails.

Éditer une image avec une URL de référence

Imaginez une équipe catalogue souhaitant le même cliché produit sur un fond de studio propre. La solution tentante est /v1/images/edits. La documentation l'exclut. Les requêtes d'image de référence Nano Banana sont exposées sur /v1/images/generations avec operation: "image-to-image". /v1/images/edits n'est pas le bon chemin pour elles.

Cette requête provient du guide de génération d'images, avec nano-banana-2 comme modèle :

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Règles que nous suivons avec cette structure :

• Envoyez exactement les champs de référence documentés. Utilisez image_url, image_urls ou reference_image_urls en JSON. N'envoyez pas de images[] ou file_id au niveau racine. Ceux-ci appartiennent au flux d'édition et sont rejetés sur cet endpoint.
• Utilisez des URL publiques. Elles doivent être en http ou https, sans identifiants intégrés, sans fragments et sans hôtes de réseau privé. Évitez les URL signées qui pourraient expirer avant le début du traitement.
• Utilisez le multipart pour les sources privées. La documentation propose un fichier image en multipart pour les sources privées ou protégées par en-tête.
• Faites correspondre resolution au modèle. La documentation indique que nano-banana-pro peut l'inclure et que nano-banana-edit devrait l'omettre. La documentation nomme également nano-banana-edit comme un modèle d'image de référence, mais cet ID ne figure pas dans le catalogue que nous avons récupéré le 02/10/2026. Vérifiez tout ID par rapport à /v1/models avant de l'utiliser.

L'exemple d'édition par chat-completions de l'article source a disparu. L'enregistrement en direct liste gemini_generate_content comme format accepté pour nano-banana-2 et nano-banana-pro. Nos données ne documentent pas de chemin d'édition d'image via chat-completions.

L'inpainting basé sur un masque et les paramètres tels que strength ne sont pas documentés pour Nano Banana dans nos données. Inspectez GET /v1/models/{model} avant de les envoyer.

Quand une requête d'image devient une tâche, et comment la poller

Un appel de création d'image est soit synchrone, soit asynchrone, et la réponse vous indique lequel. Le guide des tâches asynchrones liste les champs déclencheurs : task_id, status: "pending" ou poll_url. Si l'un d'eux apparaît, le tableau data[] est vide et le travail est toujours en cours.

Nos données documentent le flag de requête async: true uniquement pour gpt-image-2 et les modèles d'image officiels FLUX/BFL. Il n'est pas documenté pour les IDs Nano Banana. Ne l'ajoutez pas à une requête Nano Banana. Gérez une réponse de tâche si elle revient, et vérifiez les détails du modèle si vous avez besoin d'un comportement asynchrone.

Imaginez un rafraîchissement de navigateur qui renvoie l'appel de création après une réponse lente. Vous payez alors pour deux générations. La documentation indique que la plupart des générations en double proviennent de cette nouvelle tentative. Suivez cet ordre :

1. Sauvegardez les IDs immédiatement. Stockez id ou task_id, poll_url, le modèle, l'endpoint et votre propre ID de travail. id et task_id sont la même valeur.
2. Pollez l'URL. Utilisez poll_url lorsqu'elle est présente. Sinon, appelez la route fixe :

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. Pollez toutes les 5 à 10 secondes. Le guide indique que c'est généralement suffisant pour les longs travaux média.
2. Connaissez les statuts. Ils sont pending, processing, completed et failed. Une tâche annulée affiche failed avec cancelled: true.
3. Arrêtez-vous à un statut terminal. Sur completed, lisez data[].url. Les résultats d'image asynchrones sont uniquement des URL, jamais de b64_json. Sur failed, lisez error et error_details.
4. Gérez les timeouts en toute sécurité. Si un appel de création expire avant que vous ne voyiez une réponse, vérifiez le request_id et cherchez une tâche avant de réessayer. Si vous avez stocké un ID de tâche, reprenez le polling. Si un polling de statut échoue, réessayez ce polling avec un backoff et ne recréez pas la tâche.

Une lecture de statut renvoie un HTTP 200 même pour une tâche échouée. Les tâches échouées peuvent inclure error_details avec status, type, code, message, param et retryable. Par exemple, error_details.status: 400 avec param: "size" signifie que la requête nécessite une correction. Cela ne signifie pas que le polling lui-même a échoué. Réessayer une génération échouée crée une nouvelle tâche et peut créer une nouvelle facturation.

Erreurs à attendre et quoi faire

Gérez les erreurs par statut HTTP et code, jamais par message. Le guide de gestion des erreurs indique que le message peut changer sans préavis. Chat Completions et Responses utilisent un objet error de style OpenAI, tandis que les formats Gemini et Anthropic conservent leurs propres structures. Ne partagez pas un seul parseur pour toutes les API TokenLab.

Statut / code	Cause probable	Que faire
400, param: "model"	Pas de modèle explicite	Envoyez model. Listez les IDs avec /v1/models?recommended_for=image.
400 champ non supporté, ou unsupported_parameter	Un champ que le modèle ne documente pas, comme resolution sur un modèle sans cette option	Supprimez le champ ou changez de modèle. Ne répétez pas sans changement.
400 sur une image de référence	Mauvais endpoint, ou URL privée/expirée	Utilisez /v1/images/generations avec image_urls. Utilisez une URL publique et stable.
401 invalid_api_key ou expired_api_key	Clé manquante, révoquée ou expirée	Remplacez la clé.
402 insufficient_balance ou quota_exceeded	Solde trop bas, ou la clé a atteint sa limite	Ajoutez des fonds, augmentez la limite de la clé ou choisissez un modèle moins cher.
403 model_not_allowed	La clé ne peut pas utiliser ce modèle	Mettez à jour la liste des modèles de la clé.
404 model_not_found	ID inconnu ou indisponible	Lisez /v1/models et utilisez un ID actuel.
413 payload_too_large	Requête ou fichier trop volumineux	Réduisez l'entrée.
429 rate_limit_exceeded	Trop de requêtes dans la fenêtre	Attendez le Retry-After, puis réessayez.
500–504, all_channels_failed	Problème de service ou d'approvisionnement	Réessayez uniquement quand retryable est true. Respectez retry_after et plafonnez les tentatives.

Une erreur 503 all_channels_failed ne signifie pas toujours une panne. Si retryable est false et que retry_after est manquant, l'opération n'a pas d'approvisionnement dans le palier de livraison sélectionné. Répéter la requête n'aidera pas ; vérifiez donc d'abord GET /v1/models.

Le polling de tâche a ses propres échecs :

• 404 async_task_not_found : la tâche a expiré ou n'existe plus. Vérifiez le task_id et la poll_url sauvegardés.
• 403 task_not_owned : la tâche appartient à un autre espace de travail. Vérifiez à quel espace de travail appartient la clé API.
• Une tâche terminée sans URL média : traitez-la comme échouée. Gardez les IDs et contactez le support.

Lorsque vous contactez le support, envoyez le request_id, le task_id, le billing_transaction_id lorsqu'il est présent, l'endpoint, le modèle, l'heure et les noms de champs. N'envoyez jamais de clés, de médias privés ou d'URL signées.

Comment la facturation d'une requête d'image est déterminée

Les trois IDs Nano Banana payants utilisent l'unité per_image ; le prix affiché est donc le prix per_request du modèle. Le guide de facturation ajoute les règles suivantes :

• Un résultat, une facturation. Chaque requête terminée est facturée une fois, pour l'option de livraison qui l'a produite. TokenLab Verified utilise les prix publics TokenLab. Official utilise la couche de prix officielle. Auto essaie d'abord Verified, puis Official.
• Les paliers définissent le montant final. Les fourchettes de prix en direct (0,0225 $ à 0,0755 $ pour nano-banana-2, 0,067 $ à 0,12 $ pour nano-banana-pro) montrent qu'un prix fixe unique ne couvre pas chaque requête. Les paliers de résolution sont probablement le facteur déterminant, mais confirmez cela dans les entrées de tarification du modèle.
• Les tâches réservent d'abord. Une tâche asynchrone peut réserver son coût estimé lorsqu'elle est acceptée. Une tâche terminée est facturée une fois, et une tâche échouée libère ou rembourse le montant en attente. Le guide de facturation indique qu'une tâche échouée n'est pas facturée.
• Un tiret n'est pas gratuit. Sur la page des modèles, un tiret dans la colonne de prix TokenLab signifie qu'aucune offre Verified n'est disponible pour le moment.

Pour confirmer une facturation, utilisez ces endroits :

1. GET /v1/models/:model/pricing ou l'API de tarification pour le prix actuel.
2. La console, qui affiche l'estimation maximale avant que vous ne confirmiez la génération payante.
3. Usage pour la facturation finale par modèle.
4. billing_transaction_id dans la réponse ou la tâche, et l'en-tête X-Billing-Transaction-ID. Le streaming et certains formats natifs peuvent l'exposer uniquement dans l'en-tête.

Si Usage n'affiche pas la facturation finale ou le montant libéré après la fin d'une tâche, envoyez le Request ID et le task ID à support@tokenlab.sh. Ne copiez pas les prix de cet article dans votre code. Le guide de facturation indique de lire le prix actuel lorsque votre application doit afficher ou comparer des coûts.

FAQ

Quel ID de modèle Nano Banana dois-je envoyer pour des requêtes image-to-image ?

Les enregistrements en direct listent image-to-image pour nano-banana-2, nano-banana-2-lite et nano-banana-pro. La documentation nomme également nano-banana-edit, mais il ne figure pas dans le catalogue que nous avons récupéré le 02/10/2026. Envoyez l'ID avec operation: "image-to-image" et image_urls vers /v1/images/generations. Effectuez un petit test sur vos propres images, car nos données ne contiennent pas de comparaison de qualité.

Pourquoi ma requête d'image a-t-elle renvoyé un task_id au lieu d'une image ?

L'appel de création s'est exécuté en tant que tâche asynchrone. Cherchez task_id, status: "pending" ou poll_url dans la réponse. Sauvegardez ces champs, puis pollez poll_url ou GET /v1/tasks/{id} toutes les 5 à 10 secondes jusqu'à ce que le statut soit completed ou failed. N'envoyez pas une seconde requête de création pendant que vous attendez.

Puis-je obtenir une sortie base64 d'un modèle Nano Banana ?

Le champ response_format accepte url ou b64_json, et une requête synchrone peut renvoyer data[].b64_json. Les résultats d'image asynchrones sont uniquement des URL, quel que soit le format demandé. Vérifiez les détails du modèle sélectionné pour confirmer qu'il accepte b64_json, car les champs diffèrent selon le modèle.

Une tâche d'image échouée est-elle facturée ?

Le guide de facturation indique qu'une tâche échouée n'est pas facturée, et toute réservation en attente est libérée ou remboursée. Réessayer une génération échouée crée une nouvelle tâche et peut créer une nouvelle facturation. Confirmez le résultat dans Usage en utilisant le billing_transaction_id et le task_id.

Créez une clé dans le tableau de bord TokenLab, envoyez la requête text-to-image ci-dessus avec nano-banana-2-lite, et vérifiez la facturation dans Usage.