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

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

Para utilizar la API de Imágenes Nano Banana, primero dirígete a la consola de Ace Data Cloud para obtener tu token de API, que debes guardar como respaldo.

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.

📘 Documentación completa: API de Imágenes Nano Banana →

Resumen de la interfaz

URL base: https://api.acedata.cloud
Endpoint: POST /nano-banana/images
Método de autenticación: Incluir en el encabezado HTTP 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, 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; cada imagen se genera mediante una llamada independiente; fallos técnicos comunes o rechazos de seguridad del proveedor solo afectan a la llamada correspondiente, las demás imágenes exitosas se devuelven normalmente y se facturan según el número real de 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)

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

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

{
  "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 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://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. data solo contiene las imágenes generadas con éxito y se factura según el número real devuelto. Cada llamada de generación utiliza obligatoriamente la política de seguridad nativa del proveedor; si una llamada es rechazada, no afectará a otras llamadas exitosas, si todas las llamadas son rechazadas, se devuelve 403.
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 imágenes

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 una descripción del objetivo de la edición en prompt. Por ejemplo, aquí proporcionamos una foto de una persona y una foto de ropa, para que la persona use esa ropa, se pueden enviar los enlaces de las imágenes 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)

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)

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

{
  "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 URL 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:

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).
La API devolverá inmediatamente una respuesta que contiene task_id (o resultados básicos).
Cuando la tarea esté completa, la plataforma enviará el JSON completo a callback_url mediante 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):

{
  "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.
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 cobrará; las solicitudes de múltiples imágenes aún pueden devolver y cobrar otras llamadas exitosas.
429 too_many_requests: frecuencia de solicitudes excedida.
500 api_error: excepción del servidor.

Ejemplo de respuesta de error

{
  "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.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Proxy

Avanzado

Coding

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

Proceso de solicitud

Resumen de la interfaz

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

Ejemplo de solicitud (cURL)

Ejemplo de solicitud (Python)

Ejemplo de respuesta exitosa

Descripción de campos

Editar imágenes (`action=edit`)

Ejemplo de solicitud (cURL)

Ejemplo de solicitud (Python)

Ejemplo de respuesta exitosa

Descripción de campos

Callback asíncrono (opcional, recomendado)

Manejo de errores

Ejemplo de respuesta de error

Correspondencia de parámetros y consideraciones

​Proceso de solicitud

​Resumen de la interfaz

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

​Ejemplo de solicitud (cURL)

​Ejemplo de solicitud (Python)

​Ejemplo de respuesta exitosa

​Descripción de campos

​Editar imágenes (action=edit)

​Ejemplo de solicitud (cURL)

​Ejemplo de solicitud (Python)

​Ejemplo de respuesta exitosa

​Descripción de campos

​Callback asíncrono (opcional, recomendado)

​Manejo de errores

​Ejemplo de respuesta de error

​Correspondencia de parámetros y consideraciones

Proceso de solicitud

Resumen de la interfaz

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

Ejemplo de solicitud (cURL)

Ejemplo de solicitud (Python)

Ejemplo de respuesta exitosa

Descripción de campos

Editar imágenes (`action=edit`)

Ejemplo de solicitud (cURL)

Ejemplo de solicitud (Python)

Ejemplo de respuesta exitosa

Descripción de campos

Callback asíncrono (opcional, recomendado)

Manejo de errores

Ejemplo de respuesta de error

Correspondencia de parámetros y consideraciones