Nano Banana Images API Documentation

​

Processus de demande

📘 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 ; chaque image est générée par un appel indépendant ; les échecs techniques normaux ou les refus de sécurité du fournisseur n’affectent que l’appel correspondant, les autres images réussies sont retournées normalement et facturées selon le nombre d’images réussies

​

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

​

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 par 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 par 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 par 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 pour la génération ou l’édition, prend en charge 1 à 4, par défaut 1. data ne contient que les images générées avec succès et est facturé selon le nombre d’images retournées. Chaque appel de génération utilise obligatoirement la politique de sécurité native du fournisseur ; un appel refusé n’affecte pas les autres appels réussis, si tous les appels sont refusés, un 403 est retourné.
• data[] : Liste des résultats.
  • prompt : Texte d’invite utilisé pour la génération (écho).
  • 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)

​

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 réponse réussie

{
  "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 réaliser l’édition.
• Les autres champs sont les mêmes que ceux retournés par « génération d’images ».

​

Callback asynchrone (optionnel, recommandé)

1. 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).
2. L’API renverra immédiatement une réponse contenant task_id (ou contenant les résultats de base).
3. Lorsque la tâche est terminée, la plateforme enverra le JSON complet à callback_url via POST. Vous pouvez associer la requête et le résultat par task_id.

{
  "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

• 400 token_mismatched : requête non valide 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.
• 403 forbidden : la politique de sécurité native du fournisseur a refusé la requête ou le résultat généré. Cet appel ne renverra pas d’image et ne sera pas facturé ; les demandes multiples peuvent toujours renvoyer et facturer d’autres appels réussis.
• 429 too_many_requests : fréquence de requêtes dépassée.
• 500 api_error : exception côté 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 les versions officielles correspondantes :official), aspect_ratio (rapport 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 : il est nécessaire de fournir authorization: Bearer {token} ; accept est recommandé d’être défini sur application/json
• Accessibilité des images : image_urls doit être des liens directs accessibles publiquement (HTTP/HTTPS), il est recommandé d’utiliser HTTPS
• Idempotence et suivi : conservez task_id et trace_id pour faciliter le dépannage et l’association des résultats