API de Nano Banana Pro: llamada oficial, plantillas JSON/YAML y errores

La respuesta corta, a 20 de julio de 2026, es esta: la ficha oficial del modelo identifica Nano Banana Pro como Gemini 3 Pro Image, con model ID gemini-3-pro-image, y la documentación de Interactions 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.

“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?

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 declara entrada Text/Image, no PDF. La documentación general de procesamiento de documentos 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

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 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 señala que algunas cuentas nuevas pueden necesitar un prepago mínimo de 10 USD.

Crear una 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 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 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, 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.

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.