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

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 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: Nano Banana Images API →

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)

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)

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

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

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

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 un resultado básico).
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):

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

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

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

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