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

# Nano Banana Images API Documentation

> Nano Banana Image Generation 集成指南 - XHuoAPI

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](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) sur la plateforme XHuoAPI 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.xhuoapi.ai/v1`
* **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)

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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

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

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### Exemple de requête (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "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": "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.xhuoapi.ai/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é) :

```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.xhuoapi.ai/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

```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é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