Instrucciones de integración de la API Nano Banana Images

​

Proceso de solicitud

📘 Documentación completa: Nano Banana Images API →

​

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)

​

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

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

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

​

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

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

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

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.

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

• 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

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