nano banana pro api image config no size parameter es image 0 图示

Evitar errores en la invocación de la API de Nano Banana Pro: imageConfig determina la resolución, no añada el parámetro size

por

Muchos desarrolladores, al invocar por primera vez la API de Nano Banana Pro (correspondiente al modelo gemini-3-pro-image-preview de Google), caen en la misma trampa: reutilizar el parámetro size: "1024x1024" de la era de OpenAI / DALL-E. El resultado es que la resolución de la imagen generada no cambia, reciben un error 400 o el servidor ignora el parámetro silenciosamente.

Este es el "error frecuente" más común al llamar a la API de Nano Banana Pro. Lo correcto es: la resolución se determina conjuntamente por los parámetros imageConfig.imageSize (definición 1K/2K/4K) y imageConfig.aspectRatio (relación de aspecto 1:1/16:9/…), no envíes ningún campo size. En este artículo, explicamos esto a fondo y proporcionamos código en curl, Python y Node.js listo para copiar y ejecutar.

nano-banana-pro-api-image-config-no-size-parameter-es 图示

Puntos clave de la invocación de la API de Nano Banana Pro

Antes de empezar a copiar código, recuerda estas tres reglas de oro; si las comprendes, el 90% del contenido de este artículo serán solo detalles:

  1. Correspondencia de nombres de modelo: Nano Banana Pro = gemini-3-pro-image-preview (también llamado Gemini 3 Pro Image), pertenece a la serie Gemini 3 de modelos de generación/edición de imágenes de Google. Algunos en el mercado lo llaman Nano Banana 2, pero es esencialmente lo mismo.
  2. El protocolo es nativo de Gemini: No es compatible con el protocolo de OpenAI Chat Completions. La ruta de solicitud es :generateContent, los campos de nivel superior del cuerpo de la solicitud son contents + generationConfig, no hay messages ni campos size al estilo OpenAI.
  3. Resolución = imageSize × aspectRatio: imageSize controla el nivel de definición (512 / 1K / 2K / 4K), y aspectRatio controla la relación de aspecto (1:1 / 16:9 / 9:16 / …). Ambos determinan conjuntamente los píxeles de salida finales.

📌 Resumen en una frase: Al invocar Nano Banana Pro con el protocolo Gemini, olvida por completo la costumbre de size: "1024x1024" de OpenAI. El servicio proxy de API de APIYI (apiyi.com) para Nano Banana Pro conserva íntegramente el protocolo nativo de Gemini; cualquier configuración de imageConfig válida en la documentación oficial de Google también funciona en APIYI.

Resumen de parámetros clave de Nano Banana Pro

Parámetro Ubicación Función Ejemplo de valor
imageSize generationConfig.imageConfig Nivel de definición "512" / "1K" / "2K" / "4K"
aspectRatio generationConfig.imageConfig Relación de aspecto "1:1" / "16:9" / "9:16" / "4:3" etc.
responseModalities generationConfig Modalidad de salida ["IMAGE"] (obligatorio)
contents[].parts[].text contents Indicación de texto Texto libre
contents[].parts[].inline_data contents Imagen de entrada (base64) Incluye mime_type y data

⚠️ El campo size no está en la tabla: porque simplemente no es un parámetro válido del protocolo Gemini, no lo envíes.

¿Por qué no deberías añadir el parámetro size? Razones a nivel de protocolo

Esta es la sección más importante del artículo. Vamos a analizar este tema a fondo en tres niveles.

Nivel de protocolo: Gemini y OpenAI son dos especificaciones independientes

La API de imágenes de OpenAI (DALL-E 2/3, gpt-image-1) utiliza un parámetro de cadena de texto de nivel superior size: "1024x1024"; mientras que la API de imágenes de Google Gemini 3 está diseñada con un objeto anidado imageConfig. Ambas especificaciones son independientes entre sí. Nano Banana Pro sigue el protocolo nativo de Gemini, por lo tanto:

  • ❌ size: "1024x1024" —— El protocolo de Gemini no tiene este campo.
  • ❌ size: "1K" —— No existe este campo.
  • ❌ n: 4 —— No existe el campo de OpenAI para "generar N imágenes a la vez".
  • ✅ imageConfig.imageSize: "1K" —— Correcto.
  • ✅ imageConfig.aspectRatio: "16:9" —— Correcto.

Nivel de comportamiento: ¿Qué pasa si envías size de más?

El procesamiento en el lado del servidor suele tener tres escenarios, y ninguno es el que deseas:

  1. Ignorado silenciosamente: La puerta de enlace (gateway) ascendente descarta los campos desconocidos como inválidos. Tú crees que ha funcionado, pero en realidad se genera el valor predeterminado de 1K 1:1.
  2. Error 400 directo: Las puertas de enlace con una validación de esquema estricta rechazarán la solicitud directamente debido a campos desconocidos.
  3. Impacto en la facturación/enrutamiento: Algunas capas de proxy pueden interpretar size como una señal de enrutamiento y dirigir la solicitud a una versión de endpoint incorrecta.

Nivel de ingeniería: Deuda técnica y mantenimiento caótico

Muchos equipos encapsulan las API de OpenAI, Gemini, Stability, etc., en una misma capa de invocación y tienen la costumbre de reutilizar un "campo size genérico". Parece elegante, pero en realidad es un nido de errores. Se recomienda que, al invocar interfaces nativas de Gemini como Nano Banana Pro, se utilice una cadena de transformación independiente para mapear explícitamente size a imageConfig.imageSize + imageConfig.aspectRatio, en lugar de pasar el size original directamente.

💡 Sugerencia: Al usar APIYI (apiyi.com) para invocar Nano Banana Pro, escribe una pequeña función de conversión de parámetros que descomponga cadenas como "1024x1024" en imageSize: "1K" + aspectRatio: "1:1", eliminando el problema desde la raíz.

Tabla comparativa completa de imageSize × aspectRatio

nano-banana-pro-api-image-config-no-size-parameter-es 图示

Niveles de imageSize y facturación

imageSize Límite de resolución aprox. Tokens de salida Precio unitario (ref.) Escenarios recomendados
"512" Nivel 512×512 Bajo El más económico Miniaturas / Borradores
"1K" Nivel 1024×1024 ~1120 ≈ $0.134 Recomendado por defecto
"2K" Nivel 2048×2048 ~1120 ≈ $0.134 Pósteres de alta definición
"4K" Nivel 4096×4096 ~2000 ≈ $0.24 (80% más caro) Calidad de impresión

💰 Nota sobre costes: 4K es aproximadamente un 80% más caro que 1K/2K, no utilices 4K indiscriminadamente. Para la gran mayoría de escenarios Web/App, 1K es suficiente; solo utiliza 4K si realmente necesitas ultra alta definición. Consulta los precios más recientes en el sitio web oficial de APIYI (apiyi.com).

Lista completa de compatibilidad de aspectRatio

Proporción Uso
"1:1" Avatar / Imagen cuadrada para redes sociales
"16:9" Portada de vídeo horizontal / Fondo de pantalla
"9:16" Vídeo corto vertical / Fondo de pantalla móvil
"4:3" Foto tradicional horizontal
"3:4" Foto tradicional vertical
"3:2" / "2:3" Proporción estándar DSLR
"4:5" / "5:4" Imagen única de Instagram
"21:9" Pantalla ultra ancha, estilo cinematográfico
"1:4" / "4:1" Banner alargado
"1:8" / "8:1" Formatos alargados extremos para usos especiales

Mapeo de combinaciones comunes → Píxeles finales

imageSize aspectRatio Píxeles de salida aprox.
1K 1:1 1024 × 1024
1K 16:9 1024 × 576
1K 9:16 576 × 1024
2K 1:1 2048 × 2048
2K 16:9 2048 × 1152
4K 1:1 4096 × 4096
4K 9:16 2304 × 4096
4K 21:9 4096 × 1728

Nota: Los píxeles reales pueden tener un ajuste fino de ±N píxeles debido a las reglas de alineación internas del modelo, pero esto no afecta a la nitidez visual.

Código de invocación correcto para la API de Nano Banana Pro

A continuación, presento ejemplos mínimos ejecutables en tres lenguajes. Los tres ejemplos realizan la misma tarea: introducir una imagen original + una indicación, y obtener una imagen de salida 1K en formato 1:1.

Versión curl (la más intuitiva, ideal para depurar)

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer TU-CLAVE-APIYI" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(base64 de la imagen original)"
          }
        },
        {
          "text": "Cambia esta imagen a un estilo cyberpunk, manteniendo la pose del personaje"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

Versión Python (se recomienda usar requests directamente, sin depender de ningún SDK)

import base64
import requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer TU-CLAVE-APIYI",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "Cambia esta imagen a un estilo cyberpunk, manteniendo la pose del personaje"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

Versión Node.js (fetch nativo, para evitar que el SDK elimine imageConfig)

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer TU-CLAVE-APIYI",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "Cambia esta imagen a un estilo cyberpunk, manteniendo la pose del personaje" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 Por qué recomendamos encarecidamente usar fetch / requests nativos: Es bien sabido en la industria que algunos SDK (incluyendo versiones antiguas de LiteLLM o ciertas versiones del SDK de Google para Node) filtran imageConfig como un campo desconocido, lo que hace que imageSize/aspectRatio no tengan efecto. Construir el cuerpo de la solicitud JSON directamente evita este problema al 100%. Si insistes en usar un SDK, asegúrate de actualizar a la última versión y verifica el cuerpo final mediante un console log en un interceptor de solicitudes.

Lista de errores comunes al realizar llamadas

nano-banana-pro-api-image-config-no-size-parameter-es 图示

Error 1: Incluir el parámetro 'size' al estilo OpenAI

// ❌ Incorrecto: 'size' no es un campo válido en el protocolo Gemini
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ Correcto: Elimina 'size', mantén solo 'imageConfig'
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

Error 2: Nombres de campo con guiones bajos / snake_case

Los nombres de los campos en imageConfig para la interfaz de Gemini 3 son en camelCase: imageSize, aspectRatio, responseModalities. Errores comunes:

  • ❌ image_size / aspect_ratio / response_modalities
  • ✅ imageSize / aspectRatio / responseModalities

Error 3: 'imageConfig' eliminado silenciosamente por el SDK

Como se mencionó anteriormente, algunas versiones de SDK filtran campos desconocidos. Método de depuración:

  1. Imprime el cuerpo HTTP real antes y después de la llamada al SDK.
  2. Usa mitmproxy / Charles para capturar la solicitud real que sale.
  3. Si descubres que imageConfig desaparece, usa fetch / requests nativos.

Error 4: Olvidar 'responseModalities'

// ❌ Si no configuras 'responseModalities', podría devolver texto plano en lugar de una imagen
{ "generationConfig": { "imageConfig": {...} } }

// ✅ Debes declarar explícitamente que la modalidad de retorno incluye IMAGE
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

Error 5: No implementar retroceso exponencial (exponential backoff) ante errores 429

Cuando la carga del servidor está saturada, se devuelve algo como:

{ "error": { "message": "La carga del servidor está saturada, inténtalo de nuevo más tarde", "type": "upstream_error", "code": 429 } }

La forma correcta es realizar un reintento con retroceso exponencial (3s → 6s → 12s). No reintentes inmediatamente, ya que solo empeorarás la congestión:

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3s, 6s, 12s

Error 6: Colocar incorrectamente múltiples imágenes de referencia

Nano Banana Pro admite la entrada de múltiples imágenes (imagen original + varias imágenes de referencia). Todas las imágenes deben incluirse como múltiples elementos inline_data dentro del array parts, dejando la indicación de texto al final del array:

// ✅ Correcto: Imágenes primero, texto al final
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "base64-imagen-original" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64-ref-1" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64-ref-2" } },
  { "text": "Por favor, aplica el estilo de la referencia 1 a la imagen original, usando la composición de la referencia 2" }
]

🧰 Resumen de errores: Convierte estos 6 puntos en tu "Checklist de Nano Banana Pro". Revisarlos antes de encapsular cada nueva llamada te ahorrará más del 90% de los errores básicos. El endpoint de Nano Banana Pro en APIYI (apiyi.com) sigue completamente el protocolo de Gemini, por lo que todos estos trucos son aplicables.

Desglose del flujo de invocación del usuario: ¿dónde es más probable que falle?

nano-banana-pro-api-image-config-no-size-parameter-es 图示

Muchos lectores comparten registros de invocación que coinciden casi exactamente con el flujo que proporcionas:

Frontend POST /api/generate
  → server.js extrae parámetros
  → verifica si modelKey.startsWith('nano-banana')
  → _generateViaGemini() ensambla el cuerpo de la solicitud
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → devuelve / reintenta

Vamos a marcar los puntos donde es más probable que ocurran errores:

Paso Problema común Sugerencia
Parámetros del frontend Pasar habitualmente size: "1024x1024" Separar en dos campos: imageSize + aspectRatio
Ensamblado del body en server.js Pasar erróneamente el campo size a Gemini Eliminar explícitamente size en la función de ensamblado
Enrutamiento del modelo Enrutar nano-banana a 1.5 en lugar de a 3 Pro Escribir el nombre del modelo exactamente como gemini-3-pro-image-preview
Envío de la solicitud Usar una versión del SDK con validación de esquema Cambiar a fetch nativo o actualizar el SDK a la última versión
Manejo de errores Lanzar el error 429 directamente al usuario Implementar reintento con retroceso exponencial (3 veces)
Análisis de respuesta Intentar obtenerlo como text cuando es una IMAGEN Ruta correcta: candidates[0].content.parts[0].inline_data.data

📋 En resumen: La estructura del flujo que compartiste es correcta. Solo necesitas eliminar ese campo size sobrante en la fase de "extracción de parámetros" y asegurarte de que server.js no lo vuelva a insertar fuera de generationConfig. Con eso, la cadena de llamadas quedará limpia.

Preguntas frecuentes (FAQ)

Q1: ¿Nano Banana Pro y Nano Banana 2 son lo mismo?
Sí. En la comunidad, muchos llaman a Gemini 3 Pro Image (gemini-3-pro-image-preview) como Nano Banana 2 o Nano Banana Pro; los tres nombres se refieren al mismo modelo. En APIYI (apiyi.com), el nombre del modelo debe coincidir con la documentación oficial.

Q2: ¿Qué pasa si no envío imageConfig?
El modelo utilizará sus valores predeterminados internos (normalmente 1K + 1:1). Si no te importa la resolución, puedes omitirlo; pero si tienes requisitos específicos de formato, debes enviar imageConfig explícitamente.

Q3: ¿Puedo usar el protocolo Gemini y enviar size como en OpenAI?
No es recomendable hacerlo de forma fiable. El protocolo Gemini no tiene un campo size, y enviarlo solo provocará comportamientos inesperados. Usar imageConfig.imageSize + imageConfig.aspectRatio es la forma más segura.

Q4: ¿Elegir 4K en imageSize garantiza una mejor calidad?
Los detalles serán más ricos, pero el costo casi se duplica (~$0.24 vs $0.134) y el tiempo de generación es mayor. Para imágenes web o de aplicaciones, 1K o 2K suele ser suficiente. Te sugiero probar un conjunto de imágenes reales de tu negocio y comparar visualmente antes de decidir.

Q5: ¿Qué diferencia hay entre invocar Nano Banana Pro a través de APIYI (apiyi.com) y la API oficial de Google?
APIYI proporciona una autenticación unificada al estilo OpenAI (Bearer Token), acceso desde regiones con restricciones y facturación centralizada, manteniendo el protocolo de invocación exactamente igual al formato nativo de Gemini. Esto significa que los parámetros imageConfig / aspectRatio / responseModalities que ves en la documentación oficial de Google son totalmente equivalentes en APIYI (apiyi.com).

Q6: ¿Por qué configuré imageSize: "2K" pero la salida sigue siendo 1K?
Las 3 razones más comunes: (1) Estás usando un SDK que filtra campos desconocidos, (2) el nombre del campo se escribió como image_size, o (3) la jerarquía de anidación de generationConfig es incorrecta. Captura primero el paquete de red real para confirmar si el cuerpo cumple con la especificación antes de revisar el servidor.

Q7: ¿Qué hago si recibo un límite de tasa (429) del proveedor?
Implementa un reintento con retroceso exponencial (3s/6s/12s). Si tu negocio es sensible a la latencia, considera cambiar entre diferentes grupos en tu área de trabajo de APIYI (apiyi.com) o solicitar una cuota independiente. Nunca escribas un bucle infinito de reintento inmediato, ya que las políticas de limitación seguirán bloqueándote.

Q8: ¿Hay un límite en la cantidad de imágenes de entrada?
La interfaz de Gemini 3 image tiene un límite en el tamaño total de las imágenes por solicitud (generalmente medido en MB, consulta la documentación oficial para detalles específicos). Se recomienda no superar las 4-5 imágenes de referencia y controlar el tamaño de cada una (redimensionar antes de convertir a base64), de lo contrario, podrías activar errores 413 o tiempos de espera agotados.

Resumen: Graba el "método de dos parámetros de resolución" en tu memoria muscular

Si solo puedes recordar una cosa, que sea esta:

La resolución de salida final de Nano Banana Pro = imageConfig.imageSize × imageConfig.aspectRatio. No vuelvas a enviar ningún campo size al estilo de OpenAI.

Lista de verificación completa:

  • ✅ Nombre del modelo: gemini-3-pro-image-preview
  • ✅ Endpoint: /v1beta/models/.../generateContent
  • ✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
  • ✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
  • ✅ generationConfig.responseModalities debe incluir "IMAGE"
  • ✅ Las entradas de múltiples imágenes deben ir en el array parts, con la indicación de texto al final
  • ✅ Para límites de tasa 429, utiliza retroceso exponencial (3s/6s/12s)
  • ❌ No envíes size: "1024x1024"
  • ❌ No escribas image_size / aspect_ratio (el formato snake_case es incorrecto)
  • ❌ No confíes en SDK antiguos que filtran campos desconocidos; primero captura el tráfico para confirmar

📢 Una última cosa: Si estás integrando Nano Banana Pro a través de APIYI apiyi.com, simplemente copia las plantillas de código curl / Python / Node.js proporcionadas en este artículo. Todos los parámetros cumplen estrictamente con el protocolo nativo de Gemini: copiar y pegar → cambiar la clave API → ejecutar.

Autor: Equipo de APIYI · Recopilando continuamente las mejores prácticas para la invocación de API de Modelos de Lenguaje Grande · apiyi.com

Deja un comentario