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

Antes de usar, ingrese a la plataforma XHuoAPI 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.xhuoapi.ai/v1
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.xhuoapi.ai/v1/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.xhuoapi.ai/v1/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.xhuoapi.ai/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.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'

Ejemplo de solicitud (Python)

import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/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.xhuoapi.ai/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:

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).
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 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.xhuoapi.ai/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

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 Imágenes Nano Banana

Proceso de solicitud

Resumen de la interfaz

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

Ejemplo de solicitud (cURL)

Ejemplo de solicitud (Python)

Ejemplo de respuesta exitosa

Descripción de campos

Editar imagen (`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 imagen (action=generate)

​Ejemplo de solicitud (cURL)

​Ejemplo de solicitud (Python)

​Ejemplo de respuesta exitosa

​Descripción de campos

​Editar imagen (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 imagen (`action=generate`)

Ejemplo de solicitud (cURL)

Ejemplo de solicitud (Python)

Ejemplo de respuesta exitosa

Descripción de campos

Editar imagen (`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