> ## 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 Nano Banana Images

> Nano Banana Image Generation API guide - Ace Data Cloud

Este artículo presenta la integración y el uso de la API 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 Nano Banana Images, primero obtenga su API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo para usarlo posteriormente.

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

Si aún no ha iniciado sesión o no se ha registrado, se le redirigirá automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual.

**Un solo API Token puede llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye una cuota gratuita para probar el servicio sin costo; cuando la cuota sea insuficiente, puede recargar 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)

## Descripción general de la interfaz

* **Base URL**: `https://api.acedata.cloud`
* **Endpoint**: `POST /nano-banana/images`
* **Método de autenticación**: incluir `authorization: Bearer {token}` en el HTTP Header
* **Encabezados de solicitud**:
  * `accept: application/json`
  * `content-type: application/json`
* **Acciones (action)**:
  * `generate`: genera imágenes a partir de indicaciones de texto
  * `edit`: edita basándose en imágenes proporcionadas
* **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, con velocidad de generación rápida
  * `nano-banana-2`: basado en Gemini 3.1 Flash Image Preview, calidad de nivel Pro + velocidad Flash
  * `nano-banana-2.1`: modelo de imágenes eficiente de nueva generación, admite generación y edición de imágenes en 1K, 2K y 4K
  * `nano-banana-pro`: basado en Gemini 3 Pro Image Preview, máxima calidad
  * `nano-banana:official`, `nano-banana-2-lite:official`, `nano-banana-2:official`, `nano-banana-pro:official`: versiones de canal oficial de los modelos correspondientes, con mejor calidad de imagen y estabilidad, y facturación diferente
* **Callback asíncrono**: opcional; recibe notificaciones de finalización de tareas y resultados mediante `callback_url`
* **Cantidad de imágenes**: opcional; especifique entre 1 y 4 mediante `count`, siendo 1 el valor predeterminado; cada imagen se completa mediante una llamada de generación independiente; los fallos técnicos normales o los rechazos de seguridad del proveedor solo afectan a la llamada correspondiente, las demás imágenes generadas correctamente se devuelven como de costumbre y se facturan según la cantidad real de imágenes generadas correctamente

## Inicio rápido: generar imágenes (`action=generate`)

**Parámetros mínimos obligatorios**: `action`, `prompt`<br />
Cuando solo desee generar una imagen directamente a partir de una indicación, establezca `action` en `generate` y proporcione 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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}
```

### Descripción de campos

* `success`: indica si esta solicitud se realizó correctamente.
* `task_id`: ID de la tarea.
* `trace_id`: ID de seguimiento de la cadena, útil para solucionar problemas.
* `count`: cantidad de imágenes solicitadas para generar o editar; admite de 1 a 4, siendo 1 el valor predeterminado. `data` solo contiene las imágenes generadas correctamente y se factura según la cantidad real de imágenes devueltas. Cada llamada de generación utiliza obligatoriamente la política de seguridad nativa del proveedor; el rechazo de una llamada no afecta a otras llamadas exitosas; cuando todas las llamadas son rechazadas, se devuelve 403.
* `data[]`: lista de resultados.
  * `prompt`: indicación utilizada para la generación (devuelta como eco).
  * `image_url`: URL directa de la imagen generada.

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

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

Cuando desee editar basándose en imágenes existentes, establezca `action` en `edit` y pase una lista de enlaces de imágenes que se editarán (una o varias) mediante `image_urls`, proporcionando al mismo tiempo un `prompt` que describa el objetivo de la edición.

Por ejemplo, aquí proporcionamos una foto de una persona y una foto de ropa; para hacer que la persona use esa ropa, puede pasar simultáneamente los enlaces de las imágenes y especificar `action` como `edit`. La URL puede ser una URL HTTP, un enlace públicamente accesible con protocolo `https` o `http`, o 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": "let this man wear on this T-shirt",
    "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": "let this man wear on this 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())
```

### 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": "let this man wear on this T-shirt",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### Descripción de los campos

* `image_urls[]`: lista de URL de imágenes que se editarán (deben ser accesibles públicamente). Se pueden enviar varias imágenes; el servicio combinará estos materiales con `prompt` para completar la edición.
* Los demás campos son iguales que los de la respuesta de «generar imagen».

***

## Devolución de llamada asíncrona (opcional, recomendada)

La generación o edición puede requerir cierto tiempo. Para evitar que las conexiones largas consuman recursos, se recomienda utilizar una **devolución de llamada de Webhook** mediante `callback_url`:

1. Añade `callback_url` al cuerpo de la solicitud, por ejemplo, la dirección Webhook de tu servidor (debe ser accesible públicamente y admitir POST JSON).
2. La API **devolverá inmediatamente** una respuesta que incluye `task_id` (o incluye un resultado básico).
3. Cuando se complete la tarea, la plataforma enviará el JSON completo a `callback_url` mediante `POST`. Puedes asociar la solicitud y el resultado a través de `task_id`.

**Ejemplo de carga útil de devolución de llamada** (la estructura de los campos es coherente con la respuesta exitosa síncrona):

```json theme={null}
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "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 y un ID de seguimiento. Los errores comunes son los siguientes:

* **400 `token_mismatched`**: la solicitud no es válida o hay un error en los parámetros.
* **400 `api_not_implemented`**: la interfaz no está implementada (contacta con soporte).
* **401 `invalid_token`**: error de autenticación o falta el Token.
* **403 `forbidden`**: la política de seguridad nativa del proveedor rechazó la solicitud o el resultado generado. Esta llamada no devolverá imágenes ni se facturará; las solicitudes con múltiples imágenes aún pueden devolver y facturar otras llamadas exitosas.
* **429 `too_many_requests`**: se superó el límite de frecuencia de solicitudes.
* **500 `api_error`**: excepción del servidor.

### Ejemplo de respuesta de error

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

***

## Correspondencia de parámetros y consideraciones

* **Obligatorios**: `action`, `prompt`
* **Exclusivos para edición**: `image_urls` (matriz, al menos 1 elemento)
* **Opcionales**: `model` (el valor predeterminado es `nano-banana`; opcionalmente `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-2.1`, `nano-banana-pro`; excepto `nano-banana-2.1`, también existen las versiones de canal oficial correspondientes con `:official`), `aspect_ratio` (relación de aspecto, como `1:1`, `16:9`), `resolution` (resolución, como `1K`, `2K`, `4K`; `nano-banana-2-lite` solo admite `1K`), `callback_url` (para devoluciones de llamada asíncronas)
* **Headers**: se debe proporcionar `authorization: Bearer {token}`; se recomienda establecer `accept` en `application/json`
* **Accesibilidad de las imágenes**: `image_urls` debe consistir en enlaces directos accesibles públicamente (HTTP/HTTPS); se recomienda usar HTTPS
* **Idempotencia y seguimiento**: conserva `task_id` y `trace_id` para facilitar la resolución de problemas y la asociación de resultados


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.