> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana Images API Documentation

> Nano Banana Image Generation API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) pour le garder en réserve.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)

## 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)

```bash theme={null}
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)

```python theme={null}
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

```json theme={null}
{
  "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)

```bash theme={null}
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)

```python theme={null}
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

```json theme={null}
{
  "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` :

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** (structure des champs identique au retour réussi synchronisé) :

```json theme={null}
{
  "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

```json theme={null}
{
  "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