Guide d’intégration de l’API Nano Banana Images

​

Processus de demande

📘 Documentation complète : Nano Banana Images API →

​

Aperçu de l’interface

• Base URL : https://api.acedata.cloud
• Endpoint : POST /nano-banana/images
• Méthode d’authentification : inclure authorization: Bearer {token} dans le HTTP Header
• En-têtes de requête :
  • accept: application/json
  • content-type: application/json
• Actions (action) :
  • generate : génère une image à partir d’un prompt textuel
  • edit : édite une image à partir d’une image donnée
• Modèles (model) (facultatif) :
  • nano-banana (par défaut) : basé sur Gemini 2.5 Flash Image, rapide et économique
  • nano-banana-2-lite : basé sur Gemini 3.1 Flash Lite Image, prend uniquement en charge 1K, vitesse de génération rapide
  • nano-banana-2 : basé sur Gemini 3.1 Flash Image Preview, qualité de niveau Pro + vitesse Flash
  • nano-banana-2.1 : modèle d’image efficace de nouvelle génération, prend en charge la génération et l’édition en 1K, 2K et 4K
  • 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 via les canaux officiels des modèles correspondants, avec une meilleure qualité d’image et stabilité, et une tarification différente
• Callback asynchrone : facultatif, recevez les notifications de fin de tâche et les résultats via callback_url
• Nombre d’images : facultatif, spécifiez 1 à 4 images via count, 1 image par défaut ; chaque image est réalisée par un appel de génération indépendant ; les échecs techniques ordinaires ou les refus de sécurité du fournisseur n’affectent que l’appel correspondant, les autres images réussies sont retournées normalement, et la facturation est basée sur le nombre réel 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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​

Exemple de réponse en cas de succès

{
  "success": true,
  "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "data": [
    {
      "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}

​

Description des champs

• success : indique si cette requête a réussi.
• task_id : ID de la tâche.
• trace_id : ID de traçage de la chaîne, utile pour diagnostiquer les problèmes.
• count : nombre d’images demandées pour la génération ou l’édition, prend en charge 1 à 4, 1 par défaut. data contient uniquement les images générées avec succès, et la facturation est basée sur le nombre réel d’images retournées. Chaque appel de génération utilise obligatoirement la politique de sécurité native du fournisseur ; le refus d’un appel n’affecte pas les autres appels réussis, et un code 403 est retourné lorsque tous les appels sont refusés.
• data[] : liste des résultats.
  • prompt : prompt utilisé pour la génération (renvoyé tel quel).
  • 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": "let this man wear on this 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": "let this man wear on this 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 en cas de succès

{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "let this man wear on this 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 à modifier (doivent être accessibles publiquement). Plusieurs images peuvent être transmises ; le service combinera ces ressources avec le prompt pour effectuer la modification.
• Les autres champs sont identiques au retour de « Génération d’images ».

​

Rappel asynchrone (facultatif, recommandé)

1. Ajoutez callback_url au corps de la requête, par exemple l’adresse Webhook de votre serveur (doit être accessible publiquement et prendre en charge POST JSON).
2. L’API renverra immédiatement une réponse contenant task_id (ou contenant les résultats de base).
3. Une fois la tâche terminée, la plateforme enverra le JSON complet à callback_url via POST. Vous pouvez associer la requête et le résultat grâce à task_id.

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "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 rejeté la requête ou le résultat généré. Cet appel ne renverra pas d’image et ne sera pas facturé ; les requêtes multi-images peuvent toujours renvoyer et facturer les autres appels réussis.
• 429 too_many_requests : fréquence des requêtes dépassant la limite.
• 500 api_error : exception côté serveur.

​

Exemple de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Correspondance des paramètres et remarques

• Obligatoires : action, prompt
• Réservé à la modification : image_urls (tableau, au moins 1 élément)
• Facultatifs : model (par défaut nano-banana, options : nano-banana-2-lite, nano-banana-2, nano-banana-2.1, nano-banana-pro ; à l’exception de nano-banana-2.1, des versions de canal officiel :official correspondantes sont également disponibles), aspect_ratio (rapport largeur-hauteur, tel que 1:1, 16:9), resolution (résolution, telle que 1K, 2K, 4K ; nano-banana-2-lite ne prend en charge que 1K), callback_url (utilisé pour les rappels asynchrones)
• Headers : vous devez fournir authorization: Bearer {token} ; il est recommandé de définir accept sur application/json
• Accessibilité des images : image_urls doit être un lien direct accessible publiquement (HTTP/HTTPS) ; l’utilisation de HTTPS est recommandée
• Idempotence et traçage : conservez task_id et trace_id afin de faciliter le dépannage et l’association des résultats