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

# Instrucciones de integración de la API de Nano Banana Images

> Nano Banana Image Generation API guide - Ace Data Cloud

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

## Proceso de solicitud

Para utilizar la API de Nano Banana Images, primero dirígete a [la consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu token de API, que debes guardar como respaldo.

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

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual.

**Un token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio.** La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en [la consola](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)

## Resumen de la interfaz

* **Base URL**: `https://api.acedata.cloud`
* **Endpoint**: `POST /nano-banana/images`
* **Método de autenticación**: Incluir en el HTTP Header `authorization: Bearer {token}`
* **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 imágenes basadas en una imagen dada
* **Modelos (model)** (opcional):
  * `nano-banana` (predeterminado): Basado en Gemini 2.5 Flash Image, rápido y de bajo costo
  * `nano-banana-2-lite`: Basado en Gemini 3.1 Flash Lite Image, solo admite 1K, velocidad de generación rápida
  * `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
  * `nano-banana:official`, `nano-banana-2-lite:official`, `nano-banana-2:official`, `nano-banana-pro:official`: Versiones oficiales de los modelos correspondientes, mejor calidad de imagen y estabilidad, con facturación diferente
* **Callback asíncrono**: Opcional, recibir notificaciones de finalización de tareas y resultados a través de `callback_url`
* **Número de imágenes**: Opcional, especificar de 1 a 4 imágenes a través de `count`, por defecto 1; si hay fallos, solo se devolverán y facturarán las imágenes exitosas

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

**Parámetros mínimos requeridos**: `action`, `prompt`
Cuando solo deseas generar una imagen directamente a partir de un texto de indicación, establece `action` como `generate` y proporciona un `prompt` claro.

### Ejemplo de solicitud (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 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 taller rústico, 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.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 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 taller rústico, 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": "70e6931b-6e34-43db-9e36-8765e2809d04",
  "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2",
  "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 taller rústico, 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://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.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.
* `count`: Número de imágenes solicitadas para generar o editar, admite de 1 a 4, por defecto 1. Si hay fallos, `data` solo contiene imágenes exitosas.
* `data[]`: Lista de resultados.
  * `prompt`: Texto de indicación utilizado para la generación (eco).
  * `image_url`: URL directa de la imagen generada.

> Nota: Solo se requiere `action` y `prompt` para generar imágenes en `/nano-banana/images`

## Editar imágenes (`action=edit`)

Cuando deseas editar una imagen existente, establece `action` como `edit` y proporciona una lista de enlaces de imágenes a editar a través de `image_urls` (1 o más), al mismo tiempo que ofreces 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 esa camiseta, se pueden enviar ambos enlaces de imagen y especificar `action` 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.acedata.cloud/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.acedata.cloud/v8073y.png",
      "https://cdn.acedata.cloud/44xlah.png"
    ],
    "count": 1
  }'
```

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

### 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.acedata.cloud/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 enviar varias, el servicio combinará estos materiales con el `prompt` para completar la edición.
* Los demás campos son los mismos que los de la respuesta de "generar imagen".

***

## Callback asíncrono (opcional, recomendado)

La generación o edición puede requerir cierto tiempo. Para evitar que las conexiones largas ocupen recursos, se recomienda usar `callback_url` para **Webhook callback**:

1. Agregue `callback_url` en el cuerpo de la solicitud, por ejemplo, la dirección de su 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 un resultado básico).
3. Cuando la tarea esté completa, la plataforma enviará el JSON completo a `callback_url` de forma `POST`. Puede 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 exitosa 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.acedata.cloud/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 de parámetros.
* **400 `api_not_implemented`**: interfaz no implementada (por favor, contacte al soporte).
* **401 `invalid_token`**: fallo de autenticación o falta de Token.
* **429 `too_many_requests`**: frecuencia de solicitudes excedida.
* **500 `api_error`**: error en el 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`, puede ser `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro`, o la versión oficial correspondiente `:official`), `aspect_ratio` (relación de aspecto, como `1:1`, `16:9`), `resolution` (resolución, como `1K`, `2K`, `4K`; `nano-banana-2-lite` solo soporta `1K`), `callback_url` (para callback asíncrono)
* **Headers**: debe proporcionar `authorization: Bearer {token}`; se recomienda establecer `accept` como `application/json`
* **Accesibilidad de imágenes**: `image_urls` debe ser un enlace directo accesible públicamente (HTTP/HTTPS), se recomienda usar HTTPS
* **Idempotencia y seguimiento**: conserve `task_id` y `trace_id` para facilitar la resolución de problemas y la asociación de resultados