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

# Instrucciones de integración de la API de Imágenes Nano Banana

> Nano Banana Image Generation 集成指南 - XHuoAPI

Este documento presenta la integración y uso de la API de Imágenes Nano Banana. Esta interfaz admite dos capacidades: **generación de imágenes (generate)** y **edición de imágenes (edit)**.

## Proceso de solicitud

Antes de usar, ingrese a la plataforma XHuoAPI en [Nano Banana Images API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) y haga clic en Acquire para solicitar la activación. La primera solicitud generalmente tendrá un límite gratuito disponible. Una vez completada la activación, podrá obtener el Bearer Token necesario para llamar a la API en la plataforma.

## Resumen de la interfaz

* **Base URL**: `https://api.xhuoapi.ai/v1`
* **Endpoint**: `POST /nano-banana/images`
* **Método de autenticación**: Se debe incluir `authorization: Bearer {token}` en el HTTP Header
* **Encabezados de solicitud**:
  * `accept: application/json`
  * `content-type: application/json`
* **Acciones (action)**:
  * `generate`: Generar imágenes según el texto de indicación
  * `edit`: Editar basado en la imagen proporcionada
* **Modelos (model)** (opcional):
  * `nano-banana` (predeterminado): Basado en Gemini 2.5 Flash Image, rápido y de bajo costo
  * `nano-banana-2`: Basado en Gemini 3.1 Flash Image Preview, calidad Pro + velocidad Flash
  * `nano-banana-pro`: Basado en Gemini 3 Pro Image Preview, calidad máxima
* **Callback asíncrono**: Opcional, recibir notificaciones de finalización de tareas y resultados a través de `callback_url`

## Comenzar rápidamente: Generar imagen (`action=generate`)

**Parámetros mínimos requeridos**: `action`, `prompt`
Cuando solo desea generar una imagen directamente a partir de un texto de indicación, establezca `action` en `generate` y proporcione un `prompt` claro.

### Ejemplo de solicitud (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 retrato fotorealista en primer plano de un anciano ceramista japonés con profundas arrugas grabadas por el sol y una cálida sonrisa comprensiva. Él está inspeccionando cuidadosamente un tazón de té recién esmaltado. El escenario es su rústico taller bañado por el sol. La escena está iluminada por una suave luz dorada que entra por una ventana, resaltando la fina textura de la arcilla. Capturado con un lente de retrato de 85 mm, resultando en un fondo suave y desenfocado (bokeh). El ambiente general es sereno y magistral. Orientación vertical del retrato.",
    "count": 1
  }'
```

### Ejemplo de solicitud (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 retrato fotorealista en primer plano de un anciano ceramista japonés "
        "con profundas arrugas grabadas por el sol y una cálida sonrisa comprensiva. Él está inspeccionando "
        "cuidadosamente un tazón de té recién esmaltado. El escenario es su rústico taller bañado por el sol. "
        "La escena está iluminada por una suave luz dorada que entra por una ventana, resaltando la fina textura "
        "de la arcilla. Capturado con un lente de retrato de 85 mm, resultando en un fondo suave y desenfocado (bokeh). "
        "El ambiente general es sereno y magistral. Orientación vertical del retrato."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### Ejemplo de respuesta exitosa

```json theme={null}
{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "Un retrato fotorealista en primer plano de un anciano ceramista japonés con profundas arrugas grabadas por el sol y una cálida sonrisa comprensiva. Él está inspeccionando cuidadosamente un tazón de té recién esmaltado. El escenario es su rústico taller bañado por el sol. La escena está iluminada por una suave luz dorada que entra por una ventana, resaltando la fina textura de la arcilla. Capturado con un lente de retrato de 85 mm, resultando en un fondo suave y desenfocado (bokeh). El ambiente general es sereno y magistral. Orientación vertical del retrato.",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}
```

### Descripción de campos

* `success`: Indica si la solicitud fue exitosa.
* `task_id`: ID de la tarea.
* `trace_id`: ID de seguimiento de la cadena, útil para la resolución de problemas.
* `data[]`: Lista de resultados.
  * `prompt`: Texto de indicación utilizado para la generación (eco).
  * `image_url`: URL directa de la imagen generada.

> Nota: `/nano-banana/images` solo requiere `action` y `prompt` para generar una imagen.

## Editar imagen (`action=edit`)

Cuando desea editar una imagen existente, establezca `action` en `edit` y pase la lista de enlaces de imágenes a editar a través de `image_urls` (1 o más), al mismo tiempo que proporciona un `prompt` que describa el objetivo de la edición.

Por ejemplo, aquí proporcionamos una foto de una persona y una foto de una camiseta, para que la persona use esta camiseta, se pueden pasar los enlaces de las imágenes y especificar la acción como `edit`, la URL puede ser una URL HTTP, accesible públicamente con el protocolo `https` o `http`, o puede ser una imagen codificada en Base64, como `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`

### Ejemplo de solicitud (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": "deja que este hombre use esta camiseta",
    "image_urls": [
      "https://cdn.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### Ejemplo de solicitud (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": "deja que este hombre use esta camiseta",
    "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())
```

### Ejemplo de respuesta exitosa

```json theme={null}
{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "deja que este hombre use esta camiseta",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### Descripción de campos

* `image_urls[]`: Lista de URLs de imágenes a editar (debe ser accesible públicamente). Se pueden pasar varias, el servicio combinará estos materiales con el `prompt` para completar la edición.
* Los demás campos son los mismos que en la respuesta de "generar imagen".

***

## Callback asíncrono (opcional, recomendado)

Generar o editar puede tardar un tiempo. Para evitar que las conexiones largas ocupen recursos, se recomienda usar **callback de Webhook** a través de `callback_url`:

1. Agrega `callback_url` en el cuerpo de la solicitud, por ejemplo, la dirección de tu Webhook en el servidor (debe ser accesible públicamente y soportar POST JSON).
2. La API **devolverá inmediatamente** una respuesta que contiene `task_id` (o resultados básicos).
3. Cuando la tarea esté completa, la plataforma enviará el JSON completo a `callback_url` de forma `POST`. Puedes asociar la solicitud con el resultado a través de `task_id`.

**Ejemplo de carga de callback** (la estructura de los campos es la misma que la respuesta de éxito sincrónica):

```json theme={null}
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "un gato siamés blanco",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}
```

***

## Manejo de errores

Cuando la llamada falla, se devolverá un formato de error estándar con un ID de seguimiento. Los errores comunes son los siguientes:

* **400 `token_mismatched`**: solicitud no válida o error en los parámetros.
* **400 `api_not_implemented`**: interfaz no implementada (por favor contacta soporte).
* **401 `invalid_token`**: fallo en la autenticación o falta de Token.
* **429 `too_many_requests`**: frecuencia de solicitudes excedida.
* **500 `api_error`**: excepción del servidor.

### Ejemplo de respuesta de error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Error interno del servidor."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

***

## Correspondencia de parámetros y consideraciones

* **Requerido**: `action`, `prompt`
* **Solo para edición**: `image_urls` (arreglo, al menos 1 elemento)
* **Opcional**: `model` (por defecto `nano-banana`, opcional `nano-banana-2` o `nano-banana-pro`), `aspect_ratio` (relación de aspecto, como `1:1`, `16:9`), `resolution` (resolución, como `1K`, `2K`, `4K`), `callback_url` (para callback asíncrono)
* **Headers**: se debe proporcionar `authorization: Bearer {token}`; se sugiere que `accept` se establezca en `application/json`
* **Accesibilidad de imágenes**: `image_urls` debe ser un enlace directo accesible públicamente (HTTP/HTTPS), se sugiere usar HTTPS
* **Idempotencia y seguimiento**: conserva `task_id` y `trace_id`, para facilitar la resolución de problemas y la asociación de resultados