Saltar al contenido principal
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 Ace Data Cloud en Nano Banana Images API 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.acedata.cloud
  • 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)

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",
    "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",
    "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": "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.acedata.cloud/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)

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

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