Nano Banana Images API Documentation

Cet article présente l’intégration et l’utilisation de l’API Nano Banana Images. Cette interface prend en charge deux capacités : génération d’images (generate) et édition d’images (edit).

Processus de demande

Pour utiliser l’API Nano Banana Images, commencez par obtenir votre API Token sur le tableau de bord Ace Data Cloud pour le garder en réserve.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion vous invitant à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle. Un API Token suffit pour appeler tous les services de la plateforme, sans avoir besoin de demander séparément pour chaque service. La première demande vous donnera un quota gratuit pour une expérience sans frais ; en cas de quota insuffisant, vous pouvez recharger le solde général sur le tableau de bord.

📘 Documentation complète : Nano Banana Images API →

Vue d’ensemble de l’API

Base URL : https://api.acedata.cloud
Endpoint : POST /nano-banana/images
Méthode d’authentification : Inclure authorization: Bearer {token} dans l’en-tête HTTP
En-têtes de requête :
- accept: application/json
- content-type: application/json
Actions (action) :
- generate : Générer une image selon le texte d’invite
- edit : Éditer une image donnée
Modèles (model) (optionnel) :
- nano-banana (par défaut) : Basé sur Gemini 2.5 Flash Image, rapide et peu coûteux
- nano-banana-2-lite : Basé sur Gemini 3.1 Flash Lite Image, prend en charge uniquement 1K, génération rapide
- nano-banana-2 : Basé sur Gemini 3.1 Flash Image Preview, qualité Pro + vitesse Flash
- nano-banana-pro : Basé sur Gemini 3 Pro Image Preview, qualité maximale
- nano-banana:official, nano-banana-2-lite:official, nano-banana-2:official, nano-banana-pro:official : Versions officielles des modèles correspondants, meilleure qualité d’image et stabilité, facturation différente
Callback asynchrone : Optionnel, recevoir des notifications de fin de tâche et des résultats via callback_url
Nombre d’images : Optionnel, spécifier 1 à 4 images via count, par défaut 1 image ; en cas d’échec partiel, seules les images réussies seront retournées et facturées

Démarrage rapide : Générer une image (`action=generate`)

Paramètres minimaux requis : action, prompt Lorsque vous souhaitez simplement générer une image directement à partir d’un texte d’invite, définissez action sur generate et fournissez un prompt clair.

Exemple de requête (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": "Un portrait en gros plan photoréaliste d'un céramiste japonais âgé avec de profondes rides gravées par le soleil et un sourire chaleureux et complice. Il inspecte soigneusement un bol à thé fraîchement émaillé. Le cadre est son atelier rustique baigné de soleil. La scène est illuminée par une douce lumière dorée de l'heure dorée filtrant à travers une fenêtre, mettant en valeur la texture fine de l'argile. Capturé avec un objectif portrait de 85 mm, résultant en un arrière-plan flou et doux (bokeh). L'ambiance générale est sereine et magistrale. Orientation portrait verticale.",
    "count": 1
  }'

Exemple de requête (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "model": "nano-banana-pro",
    "prompt": (
        "Un portrait en gros plan photoréaliste d'un céramiste japonais âgé "
        "avec de profondes rides gravées par le soleil et un sourire chaleureux et complice. Il inspecte soigneusement "
        "un bol à thé fraîchement émaillé. Le cadre est son atelier rustique baigné de soleil. La scène est illuminée "
        "par une douce lumière dorée de l'heure dorée filtrant à travers une fenêtre, mettant en valeur la texture fine "
        "de l'argile. Capturé avec un objectif portrait de 85 mm, résultant en un arrière-plan flou et doux (bokeh). "
        "L'ambiance générale est sereine et magistrale. Orientation portrait verticale."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Exemple de réponse réussie

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "Un portrait en gros plan photoréaliste d'un céramiste japonais âgé avec de profondes rides gravées par le soleil et un sourire chaleureux et complice. Il inspecte soigneusement un bol à thé fraîchement émaillé. Le cadre est son atelier rustique baigné de soleil. La scène est illuminée par une douce lumière dorée de l'heure dorée filtrant à travers une fenêtre, mettant en valeur la texture fine de l'argile. Capturé avec un objectif portrait de 85 mm, résultant en un arrière-plan flou et doux (bokeh). L'ambiance générale est sereine et magistrale. Orientation portrait verticale.",
      "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png"
    }
  ]
}

Description des champs

success : Indique si la demande a réussi.
task_id : ID de la tâche.
trace_id : ID de suivi de la chaîne, utile pour le dépannage.
count : Nombre d’images demandées à générer ou à éditer, prend en charge 1 à 4, par défaut 1. En cas d’échec partiel, data ne contient que les images réussies.
data[] : Liste des résultats.
- prompt : Texte d’invite utilisé pour la génération (retour).
- image_url : URL directe de l’image générée.

Remarque : /nano-banana/images nécessite uniquement action et prompt pour générer une image

Éditer une image (`action=edit`)

Lorsque vous souhaitez éditer une image existante, définissez action sur edit et passez la liste des liens d’images à éditer via image_urls (1 ou plusieurs images), tout en fournissant un prompt décrivant l’objectif de l’édition. Par exemple, ici nous fournissons une photo de personne et une photo de vêtement, pour faire porter ce vêtement à la personne, nous pouvons transmettre les liens d’images et spécifier l’action comme edit, l’URL peut être une URL HTTP, accessible publiquement avec le protocole https ou http, ou peut être une image encodée en Base64, comme data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

Exemple de requête (cURL)

curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "laissez cet homme porter ce T-shirt",
    "image_urls": [
      "https://cdn.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'

Exemple de requête (Python)

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "laissez cet homme porter ce T-shirt",
    "image_urls": [
        "https://cdn.acedata.cloud/v8073y.png",
        "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Exemple de retour réussi

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "laissez cet homme porter ce T-shirt",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

Description des champs

image_urls[] : liste des URL des images à éditer (doit être accessible publiquement). Plusieurs images peuvent être transmises, le service combinera ces éléments avec le prompt pour effectuer l’édition.
Les autres champs sont les mêmes que ceux du retour de « génération d’images ».

Callback asynchrone (optionnel, recommandé)

La génération ou l’édition peut prendre un certain temps. Pour éviter que les connexions longues n’occupent des ressources, il est conseillé d’utiliser un callback Webhook via callback_url :

Ajoutez callback_url dans le corps de la requête, par exemple l’adresse Webhook de votre serveur (doit être accessible publiquement, supporte POST JSON).
L’API renverra immédiatement une réponse contenant task_id (ou contenant des résultats de base).
Lorsque la tâche est terminée, la plateforme enverra le JSON complet à callback_url par POST. Vous pouvez associer la requête et le résultat via task_id.

Exemple de charge utile de callback (structure des champs identique au retour réussi synchronisé) :

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "un chat siamois blanc",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}

Gestion des erreurs

En cas d’échec de l’appel, un format d’erreur standard et un ID de suivi seront renvoyés. Les erreurs courantes sont les suivantes :

400 token_mismatched : requête illégale ou erreur de paramètre.
400 api_not_implemented : interface non implémentée (veuillez contacter le support).
401 invalid_token : échec de l’authentification ou token manquant.
429 too_many_requests : fréquence de requêtes dépassée.
500 api_error : erreur serveur.

Exemple de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Erreur interne du serveur."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Correspondance des paramètres et points à noter

Obligatoire : action, prompt
Spécifique à l’édition : image_urls (tableau, au moins 1 élément)
Optionnel : model (par défaut nano-banana, options nano-banana-2-lite, nano-banana-2, nano-banana-pro, ou version officielle correspondante :official), aspect_ratio (ratio largeur/hauteur, comme 1:1, 16:9), resolution (résolution, comme 1K, 2K, 4K ; nano-banana-2-lite ne supporte que 1K), callback_url (pour le callback asynchrone)
En-têtes : authorization: Bearer {token} doit être fourni ; accept recommandé à application/json
Accessibilité des images : image_urls doit être un lien direct accessible publiquement (HTTP/HTTPS), il est conseillé d’utiliser HTTPS
Idempotence et suivi : conservez task_id et trace_id pour faciliter le dépannage et l’association des résultats

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Proxy

Avancé

Nano Banana Images API Documentation

Processus de demande

Vue d’ensemble de l’API

Démarrage rapide : Générer une image (`action=generate`)

Exemple de requête (cURL)

Exemple de requête (Python)

Exemple de réponse réussie

Description des champs

Éditer une image (`action=edit`)

Exemple de requête (cURL)

Exemple de requête (Python)

Exemple de retour réussi

Description des champs

Callback asynchrone (optionnel, recommandé)

Gestion des erreurs

Exemple de réponse d’erreur

Correspondance des paramètres et points à noter

​Processus de demande

​Vue d’ensemble de l’API

​Démarrage rapide : Générer une image (action=generate)

​Exemple de requête (cURL)

​Exemple de requête (Python)

​Exemple de réponse réussie

​Description des champs

​Éditer une image (action=edit)

​Exemple de requête (cURL)

​Exemple de requête (Python)

​Exemple de retour réussi

​Description des champs

​Callback asynchrone (optionnel, recommandé)

​Gestion des erreurs

​Exemple de réponse d’erreur

​Correspondance des paramètres et points à noter

Processus de demande

Vue d’ensemble de l’API

Démarrage rapide : Générer une image (`action=generate`)

Exemple de requête (cURL)

Exemple de requête (Python)

Exemple de réponse réussie

Description des champs

Éditer une image (`action=edit`)

Exemple de requête (cURL)

Exemple de requête (Python)

Exemple de retour réussi

Description des champs

Callback asynchrone (optionnel, recommandé)

Gestion des erreurs

Exemple de réponse d’erreur

Correspondance des paramètres et points à noter