# API de Nano Banana Pro: llamada oficial, plantillas JSON/YAML y errores > Parte de una llamada oficial verificable y evita mezclar prompt JSON, configuración YAML, contratos de proveedor y documentos PDF en una sola petición. - URL: https://blog.laozhang.ai/es/posts/nano-banana-pro-api-guide - Published: 2026-04-01 - Updated: 2026-07-20 - Author: AI Free API Team (https://blog.laozhang.ai/es/about) - Category: Guías de API - Tags: Nano Banana Pro, Gemini 3 Pro Image, Gemini API, plantilla JSON, YAML, errores API --- La respuesta corta, a 20 de julio de 2026, es esta: la [ficha oficial del modelo](https://ai.google.dev/gemini-api/docs/models/gemini-3-pro-image) identifica Nano Banana Pro como **Gemini 3 Pro Image**, con model ID **`gemini-3-pro-image`**, y la [documentación de Interactions](https://ai.google.dev/gemini-api/docs/interactions-overview) sitúa esa API como punto de partida para una integración nueva con Google. `generateContent` sigue documentado, pero es la superficie anterior que conviene conservar para compatibilidad o migración, no mezclar con el contrato nuevo. Esta es una petición mínima para generar una imagen 16:9 a 2K. La clave vive en `GEMINI_API_KEY`, nunca en el repositorio ni en el navegador. ```bash curl -sS -X POST \ "https://generativelanguage.googleapis.com/v1beta/interactions" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-pro-image", "input": [{ "type": "text", "text": "Fotografía de producto 16:9 para una marca española de aceite de oliva. Una botella de vidrio oscuro en primer plano, etiqueta original legible, luz de mañana mediterránea y fondo de piedra caliza. No añadir precios, medallas, personas ni logotipos nuevos." }], "response_format": { "type": "image", "aspect_ratio": "16:9", "image_size": "2K" } }' ``` El ejemplo está contrastado con la documentación vigente y su JSON se puede validar localmente. No se realizó una generación de pago durante esta actualización: no había una credencial ni autorización de facturación asignadas a la tarea. Por tanto, esta página no presenta el ejemplo como un benchmark de calidad o latencia. ![Diagrama que separa endpoint, credencial, model ID, JSON y respuesta entre Gemini oficial y proveedores de Nano Banana Pro](https://blog.laozhang.ai/posts/es/nano-banana-pro-api-guide/img/cover.webp) ## “Plantilla JSON” puede significar tres cosas distintas Antes de añadir más código conviene separar tres capas. Un **objeto semántico** describe lo que el equipo quiere crear. El **JSON de transporte** contiene únicamente los campos que admite la API elegida. Un **YAML de aplicación** guarda configuración para humanos. Ninguna de las tres capas sustituye a las otras. Google no publica un esquema oficial de “prompt JSON de Nano Banana Pro”. Sus ejemplos de imagen emplean instrucciones de texto. Estructurar el brief puede reducir omisiones y facilitar revisiones, pero no garantiza por sí solo una imagen mejor. ### Capa 1: brief semántico revisable ```json { "objetivo": "hero de escritorio para una marca española de aceite de oliva", "sujeto": { "producto": "botella de vidrio oscuro", "conservar": ["texto de la etiqueta", "forma de la botella", "posición del sello"] }, "escena": { "composicion": "producto único centrado con espacio lateral", "luz": "mañana mediterránea suave", "fondo": "piedra caliza clara" }, "prohibido": ["precio", "premios inventados", "personas", "logotipos nuevos"], "salida": { "aspect_ratio": "16:9", "image_size": "2K" } } ``` Este objeto pertenece a tu aplicación. Si envías `objetivo`, `escena` o `prohibido` directamente al endpoint de Google, pueden convertirse en campos desconocidos y provocar un `400`. ### Capa 2: conversión al contrato oficial ```javascript function aInteraccionGoogle(spec) { const texto = [ spec.objetivo, `Producto: ${spec.sujeto.producto}.`, `Conservar: ${spec.sujeto.conservar.join(", ")}.`, `Composición: ${spec.escena.composicion}.`, `Luz: ${spec.escena.luz}.`, `Fondo: ${spec.escena.fondo}.`, `No incluir: ${spec.prohibido.join(", ")}.`, ].join(" "); return { model: "gemini-3-pro-image", input: [{ type: "text", text: texto }], response_format: { type: "image", aspect_ratio: spec.salida.aspect_ratio, image_size: spec.salida.image_size, }, }; } ``` La función no copia todo el objeto. Solo transforma la intención en texto y deja pasar opciones incluidas en una allowlist. Es un límite de seguridad y de compatibilidad, no un adorno arquitectónico. ### Capa 3: YAML para edición y despliegue ```yaml ruta: propietario: google superficie: interactions modelo: gemini-3-pro-image prompt: objetivo: hero de escritorio para una marca española de aceite de oliva sujeto: producto: botella de vidrio oscuro conservar: - texto de la etiqueta - forma de la botella - posición del sello escena: composicion: producto único centrado con espacio lateral luz: mañana mediterránea suave fondo: piedra caliza clara prohibido: - precio - premios inventados - personas - logotipos nuevos salida: aspect_ratio: "16:9" image_size: 2K ``` El programa debe parsear YAML, validar tipos, eliminar secretos y producir después el JSON de la ruta seleccionada. No envíes este fichero con `Content-Type: application/yaml`: Google no documenta ese contrato para Nano Banana Pro. ## El validador de seis casillas evita mezclar proveedores Pasa cualquier snippet por estas seis preguntas. Si una respuesta procede de otra documentación, detén la integración antes de probar prompts. 1. **Endpoint:** ¿es `/v1beta/interactions`, `models/...:generateContent` o una URL del proveedor? 2. **Credencial:** ¿la emite el proyecto Gemini, Cloudflare o el gateway? ¿Qué cabecera exige? 3. **Model ID:** ¿es el oficial `gemini-3-pro-image` o un alias que solo controla el proveedor? 4. **Entrada:** ¿usa `input`, `contents[].parts[]` o un `prompt` de wrapper? ¿Respeta snake_case/camelCase? 5. **Salida:** ¿devuelve image output/steps, parts con inline data, una URL o un `task_id` que hay que consultar? 6. **Errores y operación:** ¿quién posee quota, estado, logs, facturación y reglas de reintento? | Ruta | Endpoint/autenticación | Entrada y salida | Regla de no mezcla | | --- | --- | --- | --- | | Google Interactions | Google `/v1beta/interactions` + `x-goog-api-key` | `input`, `response_format`; image output/steps | Ruta recomendada para una integración directa nueva. | | Google `generateContent` | Google `models/{model}:generateContent` + la misma familia de clave | `contents.parts`, `generationConfig`; response parts | Superficie de compatibilidad; conserva su parser y casing. | | laozhang.ai | Base URL, credencial y docs del proveedor | OpenAI-compatible o `generateContent`-compatible según función | Precio, alias y respuesta son contrato del proveedor, no de Google. | | Otro wrapper async | URL y Bearer token propios | `prompt` → `task_id` → polling/webhook | No pegues su modelo o polling en un endpoint oficial. | ## Cómo guardar una imagen sin ocultar una respuesta incompleta En el SDK, la imagen única puede aparecer en `interaction.output_image`. Los outputs intercalados o más complejos requieren recorrer `steps` y los bloques `model_output`. Hay que implementar ambas ramas y fallar de forma explícita si no se guarda ninguna imagen. ```python from google import genai import base64 client = genai.Client() interaction = client.interactions.create( model="gemini-3-pro-image", input="Botella de aceite de oliva con su etiqueta original legible", response_format={ "type": "image", "aspect_ratio": "16:9", "image_size": "2K", }, ) guardadas = 0 if getattr(interaction, "output_image", None): with open("aceite-hero.png", "wb") as archivo: archivo.write(base64.b64decode(interaction.output_image.data)) guardadas += 1 else: for paso in getattr(interaction, "steps", []) or []: if getattr(paso, "type", None) != "model_output": continue for bloque in getattr(paso, "content", []) or []: if getattr(bloque, "type", None) == "image": with open(f"aceite-hero-{guardadas + 1}.png", "wb") as archivo: archivo.write(base64.b64decode(bloque.data)) guardadas += 1 if guardadas == 0: raise RuntimeError("Sin imagen: conserva respuesta, estado de seguridad y request ID") ``` Para REST, conserva primero la respuesta bruta en un registro con acceso controlado. Verifica tipo/MIME antes de decodificar base64. Un HTTP `200` sin bloque de imagen no debe contabilizarse como asset terminado. Tampoco reutilices un parser de `data[0].url` o de `task_id` si la ruta es Google Interactions. ## Compatibilidad: petición `generateContent` sin campos híbridos Una integración existente puede seguir usando la superficie anterior. La migración segura cambia una dimensión cada vez: primero model ID, luego endpoint/body y por último parser. ```bash curl -sS -X POST \ "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [{ "parts": [{"text": "Botella de aceite de oliva con su etiqueta original legible"}] }], "generationConfig": { "responseModalities": ["TEXT", "IMAGE"], "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" } } }' ``` `response_format.image_size` pertenece a Interactions. `generationConfig.imageConfig.imageSize` pertenece a `generateContent`. Aunque expresen una intención parecida, los nombres y el lugar del campo no son intercambiables. ## PDF: primero comprender el documento, luego generar la imagen La [ficha actual de `gemini-3-pro-image`](https://ai.google.dev/gemini-api/docs/models/gemini-3-pro-image) declara entrada Text/Image, no PDF. La [documentación general de procesamiento de documentos](https://ai.google.dev/gemini-api/docs/document-processing) sí admite PDF con modelos capaces de entender documentos, pero esa capacidad no se hereda automáticamente por usar la misma marca Gemini. Una ruta segura tiene dos fases: 1. **Comprensión documental.** Envía el PDF a un modelo document-capable. La ruta general documentada llega hasta 50 MB o 1.000 páginas, sujeto al modelo, región y cuota elegidos. Extrae páginas, textos, tablas, restricciones de marca y citas; valida el resultado con una persona. 2. **Producción visual.** Renderiza solo las páginas necesarias a PNG/JPEG y entrega a Pro las imágenes seleccionadas junto con el texto ya verificado. Registra orden de página, DPI, recorte y perfil de color. Para un catálogo de 120 páginas, no conviertas todo en 120 referencias. La fase uno puede seleccionar la portada, la fotografía del producto y la página de identidad visual; la fase dos utiliza únicamente esos assets. Detén el proceso si el OCR altera acentos, importes o referencias legales, si una tabla pierde su orden, o si el PDF contiene datos personales que no deben salir de su perímetro. En DOCX/HTML, convertir a texto también puede eliminar layout y contexto visual. ## Diez ratios y tres niveles de tamaño, no una promesa de píxel cuadrado La tabla específica de Nano Banana Pro documenta diez ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. Los tamaños válidos son `1K`, `2K` y `4K`, con `K` mayúscula. `4K` es una categoría y no significa `4096×4096` para todos los ratios; por ejemplo, la tabla oficial da `5504×3072` para 16:9 a 4K. El `ImageConfig` genérico enumera ratios extremos adicionales, pero no deben prometerse para Pro sin una prueba de la ruta real. La guía también habla de hasta 14 imágenes de referencia, con sublímites orientativos para objetos, personajes y estilo. Otra sección menciona un límite más estrecho para imágenes de alta fidelidad. Empieza con pocas referencias, clasifícalas por función y no prometas que catorce tendrán la misma fidelidad. ## Diagnóstico por estado HTTP, sin perder la señal | Estado | Causa que hay que descartar primero | Acción útil | | --- | --- | --- | | `400` | JSON inválido, campo desconocido, casing, ratio o size no admitido | Quita campos semánticos y valida contra el esquema de la superficie elegida. | | `401` | Clave de otro owner, cabecera incorrecta, restricción o clave bloqueada | En Google comprueba proyecto Gemini y `x-goog-api-key`; no sustituyas por un token de wrapper. | | `403` | Billing, IAM, política, región o permiso de fichero | Separa autenticación de autorización y conserva el mensaje exacto. | | `404` | Endpoint/version/model ID o URL de tarea de otro proveedor | Busca aliases preview y rutas de polling mezcladas. | | `429` | Límites de proyecto RPM/TPM/RPD/IPM o tormenta de reintentos | Respeta `Retry-After`, aplica exponential backoff con jitter y reduce concurrencia. Más keys no multiplican quota. | | `500/502/503/504` | Incidencia upstream/gateway, timeout o capacidad | Registra request ID, consulta status y usa reintentos acotados; una generación duplicada puede duplicar coste. | Una reproducción mínima incluye hora, endpoint, model ID, project, size, status, response body saneado, request ID y número de intentos. Redacta prompts y referencias si contienen datos personales o material confidencial. ## Precio oficial, Free Tier y quota pertenecen al proyecto La [tabla oficial de precios](https://ai.google.dev/gemini-api/docs/pricing?hl=es) revisada el 20 de julio de 2026 no ofrece Free Tier para Nano Banana Pro. En Standard, la imagen de 1K/2K figura a `0,134 USD` y la de 4K a `0,24 USD`. Batch y Flex muestran `0,067 USD` y `0,12 USD`. Input de texto/imagen, output de texto/pensamiento, grounding, reintentos e impuestos pueden añadir coste. La [documentación oficial de billing](https://ai.google.dev/gemini-api/docs/billing) señala que algunas cuentas nuevas pueden necesitar un prepago mínimo de `10 USD`. [Crear una API key](https://ai.google.dev/gemini-api/docs/api-key) no crea una asignación gratuita de imágenes Pro. AI Studio, la aplicación Gemini y los créditos de un proveedor son productos distintos. Los [límites de Google](https://ai.google.dev/gemini-api/docs/rate-limits) se aplican por proyecto, no por key; consulta los RPM/TPM/RPD/IPM actuales en AI Studio antes de cargar tráfico. Si el problema es capacidad, sigue la [guía para aumentar la cuota de Nano Banana Pro](https://blog.laozhang.ai/es/posts/increase-nano-banana-pro-api-quota) en lugar de rotar claves. ## Cuándo encaja laozhang.ai y cuándo parar Google directo debe seguir siendo la ruta de referencia cuando necesitas el contrato oficial. Un gateway como laozhang.ai puede encajar si valoras cambio de modelos, pago por uso, onboarding alternativo o logs de proveedor. Las docs públicas de laozhang.ai revisadas el 20 de julio de 2026 muestran el alias `gemini-3-pro-image` y un precio de proveedor de `0,09 USD/call`. Su ruta OpenAI-compatible está documentada como 1:1/1K; para ratio personalizado y 2K/4K remite a su ruta `generateContent`-compatible. No es el endpoint ni la tarifa de Google. Además, hay conflictos actuales entre algunos ratios/píxeles publicados por el proveedor y la tabla Pro de Google: usa la lista oficial de diez ratios para afirmaciones sobre el modelo y verifica la consola del proveedor para su implementación. Antes de elegirlo, comprueba la [documentación de generación de imagen del proveedor](https://docs.laozhang.ai/api-capabilities/nano-banana-pro-image), alias en consola, precio, tratamiento de llamadas fallidas, retención, límites y response contract. La documentación de edición solo debe respaldar afirmaciones sobre image editing. Si un requisito crítico no está documentado o los logs no lo confirman, conserva Google directo. No afirmes acceso ilimitado, disponibilidad garantizada, PDF directo ni reembolso automático; esas promesas se evalúan aparte en la [guía sobre acceso API sin restricciones](https://blog.laozhang.ai/es/posts/nano-banana-pro-unrestricted-api-access). ## Checklist antes de abrir tráfico - Declara el owner de la ruta: Google o proveedor. - Haz coincidir endpoint, credencial, model ID, input, output parser y error owner. - Valida el objeto semántico y permite solo ratios/sizes documentados. - Parsea JSON y YAML localmente; confirma que no contienen secretos. - Trata “sin imagen” como fallo observable, no como éxito silencioso. - Añade backoff para 429 y retry acotado para 5xx con control de duplicados. - Divide PDF/documento en comprensión y producción visual. - Revisa precio, billing, project quota y contrato del proveedor el día de lanzamiento. El orden que reduce errores es **elegir ruta → validar seis casillas → transformar el prompt → guardar la respuesta → medir coste y cuota**. Cuando se respeta, un fallo deja de ser “Nano Banana Pro no funciona” y pasa a tener un owner y una siguiente acción verificables.