Passer au contenu principal
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

Avant utilisation, veuillez accéder à Nano Banana Images API sur la plateforme Ace Data Cloud et cliquer sur Acquire pour demander l’activation. La première demande dispose généralement d’un quota gratuit disponible. Une fois l’activation terminée, vous pourrez obtenir le Bearer Token nécessaire pour appeler l’API sur la plateforme.

​
Aperçu 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
  • Action (action) :
    • generate : Générer une image en fonction d’un texte d’invite
    • edit : Éditer une image donnée
  • Modèle (model) (optionnel) :
    • nano-banana (par défaut) : Basé sur Gemini 2.5 Flash Image, rapide et peu coûteux
    • 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
  • Callback asynchrone : Optionnel, recevoir des notifications de fin de tâche et des résultats via callback_url

​
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 en fonction 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",
    "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 qui passe 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",
    "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 qui passe 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": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "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 qui passe 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://platform.cdn.acedata.cloud/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.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.
  • 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 transmettez la liste des liens d’images à éditer via image_urls (1 ou plusieurs), 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 le 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 via 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 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 (doivent être accessibles 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 de la réponse « générer une image ».

​
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 :
  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 des résultats de base).
  3. 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 (la structure des champs est identique à celle du retour de succès 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 : 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écial pour l’édition : image_urls (tableau, au moins 1 élément)
  • Optionnel : model (par défaut nano-banana, options nano-banana-2 ou nano-banana-pro), aspect_ratio (ratio largeur/hauteur, comme 1:1, 16:9), resolution (résolution, comme 1K, 2K, 4K), callback_url (pour le callback asynchrone)
  • En-têtes : Doit fournir authorization: Bearer {token} ; 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