Guía de la API de Nano Banana: Generación y edición de imágenes en TokenLab

La API de Nano Banana tiene tres IDs de modelo con precio en TokenLab, y el más barato cuesta aproximadamente la mitad por imagen que el intermedio. El error costoso rara vez es la elección del modelo. Es enviar una solicitud de edición al endpoint equivocado o reintentar una llamada de creación que ya generó una tarea. Esta guía cubre los IDs exactos, una llamada funcional de texto a imagen, una llamada de imagen de referencia, sondeo asíncrono (polling), errores esperados y cómo se establece el cargo. Los precios y las listas de campos se leyeron el 2026-10-03, así que confírmelos de nuevo antes de realizar el despliegue.

Puntos clave

• Envíe el ID exacto: nano-banana-2, nano-banana-2-lite o nano-banana-pro. Los nombres para mostrar no son alias de solicitud.
• El trabajo con imágenes de referencia para Nano Banana se envía a POST /v1/images/generations con operation: "image-to-image" y image_urls. No se envía a /v1/images/edits ni a /v1/chat/completions.
• Los precios base que leímos el 2026-10-03 son $0.0168, $0.0335 y $0.067 por imagen para los IDs lite, estándar y pro. Cada modelo tiene un rango de precios, así que confirme el nivel exacto en Usage.
• Una respuesta de creación con task_id, status: "pending" o poll_url significa que debe realizar un sondeo a GET /v1/tasks/{id} hasta que esté completed o failed.
• Una lectura de estado devuelve HTTP 200 incluso cuando la tarea ha fallado. Utilice el campo status de la tarea, no el código HTTP.
• Los cargos finales se encuentran en Usage y en billing_transaction_id, no en una tabla de precios copiada.

Modelos de la API de Nano Banana, unidades de precio y para qué sirve cada uno

Cuando comparamos el borrador anterior de esta guía con la documentación actual, encontramos tres problemas. Listaba modelos sin precios. Enviaba una edición de Nano Banana a través de chat completions. Consultaba el catálogo con un filtro que la guía de imágenes no utiliza. La tabla a continuación soluciona el primero. Las secciones posteriores solucionan los otros dos.

ID del modelo	Ideal para	Unidad de precio	Precio en TokenLab (USD)	Fuente, observado
nano-banana-2	Texto a imagen e imagen a imagen con aspect_ratio y resolution (1k, 2k, 4k). Lanzado el 2026-02-26.	per_image	$0.0335 por solicitud. Rango de $0.0225 a $0.0755.	API del modelo en vivo, 2026-10-03
nano-banana-2-lite	Texto a imagen e imagen a imagen más barato. La entrada de precio que vimos cubre el nivel 1k.	per_image	$0.0168 por solicitud. Mínimo y máximo ambos $0.0168.	API del modelo en vivo, 2026-10-03
nano-banana-pro	Texto a imagen, imagen a imagen y edición de imagen con aspect_ratio y resolution.	per_image	$0.067 por solicitud. Rango de $0.067 a $0.12.	API del modelo en vivo, 2026-10-03
nano-banana	Texto a imagen solo con aspect_ratio. Sin selección pública de resolution.	No hay evidencia	Consulte la página del modelo o el endpoint de precios	Catálogo, 2026-10-02; Documentación de Create Image, 2026-10-03

Todos los precios anteriores incluyen is_lock_price: true y fueron actualizados el 2026-10-02T16:53:30.068Z. Tres detalles importan antes de elegir uno:

• Los niveles de resolución modifican el precio. La API en vivo muestra un rango para nano-banana-2 y nano-banana-pro, pero nuestra evidencia no asigna cada nivel a una resolución. No asuma que 1k es el precio base. Lea las entradas de precios para su modelo.
• La salida de texto tiene su propio precio por token. Tanto nano-banana-2 como nano-banana-pro incluyen una entrada native-gemini-text-output. Se aplica cuando outputModality es text. Para nano-banana-2 lista 0.25 de entrada y 1.5 de salida. Para nano-banana-pro lista 1 de entrada y 6 de salida. La unidad es per_token. Confirme la escala en GET /v1/models/:model/pricing antes de presupuestar en torno a ello.
• Lite no lista ningún formato de solicitud aceptado. El registro en vivo para nano-banana-2-lite dice "no listado". Lea sus detalles antes de desarrollar sobre él.

Para un presupuesto aproximado, multiplicamos el precio base por el volumen. Estas son estimaciones al precio base, no cotizaciones:

• 100 imágenes en nano-banana-2-lite: 100 × $0.0168 = $1.68.
• 100 imágenes en nano-banana-2: 100 × $0.0335 = $3.35.
• 100 imágenes en nano-banana-pro: 100 × $0.067 = $6.70.

Los niveles de resolución más altos elevarán estas cifras.

Para listar los modelos de imagen actuales usted mismo, llame al endpoint que utiliza la guía de generación de imágenes. El borrador anterior usaba category=image, lo cual la guía no documenta.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Para las operaciones, precios y ciclo de vida de un modelo, utilice Get a Model. También puede explorar el directorio de modelos de TokenLab.

Enviar una solicitud de texto a imagen con la API de Nano Banana

Cree una clave de API en el dashboard de TokenLab y expórtela:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

Envíe siempre model. La referencia de Create Image indica que las APIs de imagen no eligen un valor predeterminado. Un modelo faltante devuelve un 400 con param: "model".

Esta solicitud utiliza solo los campos que la documentación lista para las familias de imágenes de Google. Mantuvimos resolution en 1k porque nano-banana-2 documenta 1k, 2k y 4k.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

La bandera --max-time 120 coincide con la documentación. Indican que las solicitudes de alta resolución pueden tardar cerca de un minuto o más, así que configure el tiempo de espera (timeout) de su cliente en al menos 120 segundos. La documentación dice que size es un alias de compatibilidad para las familias de imágenes de Google, pero recomiendan usar aspect_ratio directamente.

Un éxito síncrono devuelve la imagen terminada en línea. Los valores de marcador de posición a continuación muestran solo la forma documentada:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

Léalo en este orden:

1. Si el cuerpo tiene task_id, status: "pending" o poll_url, usted tiene una tarea, no una imagen. Vaya a la sección de sondeo.
2. De lo contrario, lea data[0].url. Con response_format: "b64_json", lea data[0].b64_json en su lugar.
3. created es una marca de tiempo Unix. revised_prompt aparece solo cuando el modelo devuelve uno, así que no lo requiera.
4. Almacene la URL de la imagen, su propio ID de trabajo, el modelo y el request_id de los encabezados de respuesta.

Las URLs de imágenes generadas pueden conservarse como copias multimedia durante 30 días. Verifique media_retention.items para conocer el estado de cada elemento y expires_at. Las copias pendientes o fallidas no están garantizadas, así que copie el archivo a su propio almacenamiento si lo necesita por más tiempo. La guía de retención de datos tiene los detalles.

Editar una imagen con una URL de referencia

Imagine un equipo de catálogo que desea la misma toma de producto sobre un fondo de estudio limpio. El movimiento tentador es /v1/images/edits. La documentación lo descarta. Las solicitudes de imagen de referencia de Nano Banana se exponen en /v1/images/generations con operation: "image-to-image". /v1/images/edits no es la ruta correcta para ellas.

Esta solicitud proviene de la guía de generación de imágenes, con nano-banana-2 como modelo:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Reglas que seguimos con este formato:

• Envíe exactamente los campos de referencia documentados. Use image_url, image_urls o reference_image_urls en JSON. No envíe images[] de nivel superior o file_id. Esos pertenecen al flujo de edición y son rechazados en este endpoint.
• Use URLs públicas. Deben ser http o https, sin credenciales incrustadas, sin fragmentos y sin hosts de red privada. Evite URLs firmadas que puedan expirar antes de que comience el procesamiento.
• Use multipart para fuentes privadas. La documentación ofrece un archivo image multipart para fuentes que son privadas o están protegidas por encabezados.
• Coincida resolution con el modelo. La documentación dice que nano-banana-pro puede incluirla y nano-banana-edit debería omitirla. La documentación también nombra a nano-banana-edit como un modelo de imagen de referencia, pero ese ID no está en el catálogo que obtuvimos el 2026-10-02. Verifique cualquier ID contra /v1/models antes de usarlo.

El ejemplo de edición de chat-completions del artículo fuente ya no existe. El registro en vivo lista gemini_generate_content como el formato aceptado para nano-banana-2 y nano-banana-pro. Nuestra evidencia no documenta una ruta de edición de imágenes para chat-completions.

El inpainting basado en máscaras y parámetros como strength no están documentados para Nano Banana en nuestra evidencia. Inspeccione GET /v1/models/{model} antes de enviarlos.

Cuándo una solicitud de imagen se convierte en una tarea y cómo realizar el sondeo

Una llamada de creación de imagen es síncrona o asíncrona, y la respuesta le indica cuál es. La guía de trabajos asíncronos lista los campos de activación: task_id, status: "pending" o poll_url. Si aparece alguno, la matriz data[] está vacía y el trabajo sigue ejecutándose.

Nuestra evidencia documenta la bandera de solicitud async: true solo para gpt-image-2 y los modelos de imagen oficiales FLUX/BFL. No la documenta para los IDs de Nano Banana. No la añada a una solicitud de Nano Banana. Maneje una respuesta de tarea si aparece, y verifique los detalles del modelo si necesita comportamiento asíncrono.

Imagine una actualización del navegador que vuelve a enviar la llamada de creación después de una respuesta lenta. Ahora paga por dos generaciones. La documentación dice que la mayoría de las generaciones duplicadas provienen de este reintento. Siga este orden:

1. Guarde los IDs inmediatamente. Almacene id o task_id, poll_url, el modelo, el endpoint y su propio ID de trabajo. id y task_id son el mismo valor.
2. Realice el sondeo de la URL. Use poll_url cuando esté presente. De lo contrario, llame a la ruta fija:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. Realice el sondeo cada 5–10 segundos. La guía dice que eso suele ser suficiente para trabajos multimedia largos.
2. Conozca los estados. Son pending, processing, completed y failed. Una tarea cancelada muestra failed con cancelled: true.
3. Deténgase en un estado terminal. En completed, lea data[].url. Los resultados de imágenes asíncronas son solo URLs, nunca b64_json. En failed, lea error y error_details.
4. Maneje los tiempos de espera de forma segura. Si una llamada de creación agota el tiempo de espera antes de ver una respuesta, verifique el request_id y busque una tarea antes de reintentar. Si almacenó un ID de tarea, reanude el sondeo. Si un sondeo de estado falla, reintente ese sondeo con retroceso exponencial (backoff) y no vuelva a crear.

Una lectura de estado devuelve HTTP 200 incluso para una tarea fallida. Las tareas fallidas pueden incluir error_details con status, type, code, message, param y retryable. Por ejemplo, error_details.status: 400 con param: "size" significa que la solicitud necesita corrección. No significa que el sondeo en sí haya fallado. Reintentar una generación fallida crea una nueva tarea y puede crear un nuevo cargo.

Errores a esperar y qué hacer

Maneje los errores por estado HTTP y code, nunca por message. La guía de manejo de errores dice que el mensaje puede cambiar sin previo aviso. Chat Completions y Responses utilizan un objeto error al estilo de OpenAI, mientras que los formatos de Gemini y Anthropic mantienen sus propias formas. No comparta un analizador entre todas las APIs de TokenLab.

Estado / código	Causa probable	Qué hacer
400, param: "model"	Sin modelo explícito	Envíe model. Liste IDs con /v1/models?recommended_for=image.
400 campo no soportado, o unsupported_parameter	Un campo que el modelo no documenta, como resolution en un modelo sin ella	Elimine el campo o cambie de modelo. No repita sin cambios.
400 en una imagen de referencia	Endpoint incorrecto, o una URL privada o expirada	Use /v1/images/generations con image_urls. Use una URL pública y estable.
401 invalid_api_key o expired_api_key	Clave faltante, revocada o expirada	Reemplace la clave.
402 insufficient_balance o quota_exceeded	Saldo demasiado bajo, o la clave alcanzó su propio límite	Añada fondos, aumente el límite de la clave o elija un modelo de menor precio.
403 model_not_allowed	La clave no puede usar ese modelo	Actualice la lista de modelos de la clave.
404 model_not_found	ID desconocido o no disponible	Lea /v1/models y use un ID actual.
413 payload_too_large	Solicitud o archivo demasiado grande	Reduzca la entrada.
429 rate_limit_exceeded	Demasiadas solicitudes en la ventana	Espere por Retry-After, luego reintente.
500–504, all_channels_failed	Problema de servicio o suministro	Reintente solo cuando retryable sea true. Respete retry_after y limite los intentos.

Un 503 all_channels_failed no siempre significa una interrupción. Si retryable es false y falta retry_after, la operación no tiene suministro en el nivel de entrega seleccionado. Repetir la solicitud no ayudará, así que verifique primero GET /v1/models.

El sondeo de tareas tiene sus propios fallos:

• 404 async_task_not_found: la tarea expiró o ya no existe. Verifique el task_id y poll_url guardados.
• 403 task_not_owned: la tarea pertenece a otro espacio de trabajo. Verifique a qué espacio de trabajo pertenece la clave de API.
• Una tarea completada sin URL multimedia: trátela como fallida. Mantenga los IDs y contacte a soporte.

Cuando contacte a soporte, envíe request_id, task_id, billing_transaction_id cuando esté presente, endpoint, modelo, hora y nombres de campo. Nunca envíe claves, archivos multimedia privados o URLs firmadas.

Cómo se determina el cargo por una solicitud de imagen

Los tres IDs de Nano Banana con precio utilizan la unidad per_image, por lo que el cargo principal es el precio per_request del modelo. La guía de facturación añade las reglas al respecto:

• Un resultado, un cargo. Cada solicitud completada se cobra una vez, por la opción de entrega que la produjo. TokenLab Verified utiliza los precios públicos de TokenLab. Official utiliza la capa de precios oficial. Auto intenta primero Verified, luego Official.
• Los niveles establecen la cifra final. Los rangos de precios en vivo ($0.0225 a $0.0755 para nano-banana-2, $0.067 a $0.12 para nano-banana-pro) muestran que un precio fijo no cubre todas las solicitudes. Los niveles de resolución son probablemente el factor determinante, pero confírmelo en las entradas de precios del modelo.
• Las tareas reservan primero. Una tarea asíncrona puede reservar su costo estimado cuando es aceptada. Una tarea completada se cobra una vez, y una tarea fallida libera o reembolsa el monto pendiente. La guía de facturación dice que una tarea fallida no se cobra.
• Un guion no es gratis. En la página de Modelos, un guion en la columna de precio de TokenLab significa que no hay ninguna oferta Verified disponible en este momento.

Para confirmar un cargo, utilice estos lugares:

1. GET /v1/models/:model/pricing o la API de precios para el precio actual.
2. La consola, que muestra la estimación máxima antes de confirmar la generación pagada.
3. Usage para el cargo final por modelo.
4. billing_transaction_id en la respuesta o tarea, y el encabezado X-Billing-Transaction-ID. El streaming y algunos formatos nativos pueden exponerlo solo en el encabezado.

Si Usage no muestra el cargo final o el monto liberado después de que una tarea finaliza, envíe el ID de solicitud y el ID de tarea a support@tokenlab.sh. No copie los precios de este artículo en su código. La guía de facturación dice que debe leer el precio actual cuando su aplicación necesite mostrar o comparar costos.

Preguntas frecuentes

¿Qué ID de modelo de Nano Banana debo enviar para solicitudes de imagen a imagen?

Los registros en vivo listan image-to-image para nano-banana-2, nano-banana-2-lite y nano-banana-pro. La documentación también nombra a nano-banana-edit, pero no está en el catálogo que obtuvimos el 2026-10-02. Envíe el ID con operation: "image-to-image" y image_urls a /v1/images/generations. Realice una pequeña prueba con sus propias imágenes, porque nuestra evidencia no tiene una comparación de calidad.

¿Por qué mi solicitud de imagen devolvió un task_id en lugar de una imagen?

La llamada de creación se ejecutó como una tarea asíncrona. Busque task_id, status: "pending" o poll_url en la respuesta. Guarde esos campos, luego realice el sondeo a poll_url o GET /v1/tasks/{id} cada 5–10 segundos hasta que el estado sea completed o failed. No envíe una segunda solicitud de creación mientras espera.

¿Puedo obtener salida base64 de un modelo Nano Banana?

El campo response_format acepta url o b64_json, y una solicitud síncrona puede devolver data[].b64_json. Los resultados de imágenes asíncronas son solo URLs, independientemente del formato que haya solicitado. Verifique los detalles del modelo seleccionado para confirmar que acepta b64_json, ya que los campos difieren según el modelo.

¿Se cobra una tarea de imagen fallida?

La guía de facturación dice que una tarea fallida no se cobra, y cualquier reserva pendiente se libera o reembolsa. Reintentar una generación fallida crea una nueva tarea y puede crear un nuevo cargo. Confirme el resultado en Usage usando el billing_transaction_id y el task_id.

Cree una clave en el dashboard de TokenLab, envíe la solicitud de texto a imagen anterior con nano-banana-2-lite y verifique el cargo en Usage.