Interpretación de thoughtSignature de la API Nano Banana 2: ¿Por qué no es una imagen después de la decodificación base64?

Nota del autor: Análisis profundo de la esencia del campo thoughtSignature en la respuesta de la API de Nano Banana 2: no es una imagen, sino una firma de pensamiento cifrada. Explicamos en detalle la estructura de respuesta del modo Thinking, cómo manejarla correctamente y los errores comunes.

Muchos desarrolladores, al invocar la API de Nano Banana 2 para la generación de imágenes, han notado que la respuesta, además de los datos de la imagen, contiene un campo llamado thoughtSignature. Se trata de una larga cadena codificada en base64 que, a simple vista, parece información de imagen. Sin embargo, al intentar decodificarla, resulta imposible convertirla en una imagen. ¿Qué es exactamente? En este artículo, aclararemos la naturaleza de thoughtSignature, por qué no es una imagen y cómo manejarla correctamente en conversaciones de múltiples turnos.

Valor central: Tras leer este artículo, entenderás los principios técnicos de thoughtSignature, evitarás tratarla erróneamente como una imagen y dominarás el método correcto para transmitir la firma en conversaciones de múltiples turnos.

Puntos clave de thoughtSignature en la API de Nano Banana 2

Empecemos respondiendo a la pregunta más frecuente: thoughtSignature no es una imagen, no se puede decodificar como tal; es una firma cifrada del proceso de razonamiento del modelo.

¿Cómo se ve thoughtSignature en la respuesta de la API de Nano Banana 2?

Cuando invocas a Nano Banana 2 para generar una imagen, el array parts en la respuesta de la API puede contener varios elementos. La estructura típica de la respuesta es la siguiente:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "Déjame pensar cómo generar esta imagen...",
          "thought": true
        },
        {
          "text": "",
          "thoughtSignature": "CpcHAdHtim9+q4rstcbvQC0ic4x1/vqQlCJ..."
        },
        {
          "inlineData": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUg..."
          }
        }
      ]
    }
  }]
}

Aquí hay tres part, que son:

1. Resumen de pensamiento (thought: true): Resumen textual del proceso de inferencia del modelo.
2. Firma de pensamiento (thoughtSignature): Instantánea cifrada del estado de inferencia.
3. Datos de imagen (inlineData): Los datos reales de la imagen en base64.

El problema clave es que tanto la segunda como la tercera parte contienen datos codificados en base64. Si tu código no los distingue correctamente, confundirá thoughtSignature con los datos de la imagen al intentar decodificarlos, y descubrirás que es imposible convertirlo en una imagen.

title: Principios técnicos de thoughtSignature en la API de Nano Banana 2
description: Descubre qué es thoughtSignature en la API de Nano Banana 2, cómo funciona y por qué es clave para mantener la coherencia en conversaciones multimodales.

Principios técnicos de thoughtSignature en la API de Nano Banana 2

Una vez aclarado que thoughtSignature no es una imagen, veamos qué es exactamente.

La esencia de thoughtSignature

Según la definición oficial de Google:

thoughtSignature (string, opcional): "Una firma opaca para el pensamiento, de modo que pueda reutilizarse en solicitudes posteriores. Una cadena codificada en base64".

En términos sencillos: thoughtSignature es una "instantánea de memoria" del proceso de pensamiento del modelo, que se devuelve codificada en base64 tras ser firmada criptográficamente. Su función es permitir que el modelo "recuerde" el proceso de razonamiento previo en conversaciones de varias rondas, manteniendo así la coherencia lógica.

Características clave:

• Opaca: El desarrollador no puede interpretar su contenido y no necesita preocuparse por su estructura interna.
• Firma criptográfica: Está firmada por el servidor de Google y no se puede falsificar; si envías una cadena base64 aleatoria, recibirás un error de "firma inválida".
• Con estado: Contiene la cadena de razonamiento y los resultados de los cálculos intermedios que el modelo utilizó para generar la respuesta actual.

Diferencias entre thoughtSignature y thought

Estos dos campos suelen confundirse, pero son completamente distintos:

thought es el resumen de razonamiento para que lo lean los humanos, mientras que thoughtSignature es la memoria de razonamiento para que la "lea" el modelo.

¿Por qué la API de Nano Banana 2 necesita thoughtSignature?

Nano Banana 2 pertenece a la serie Gemini 3.1 y es compatible con el modo Thinking (pensamiento). Antes de generar una imagen, el modelo realiza un razonamiento interno: analiza la intención de la indicación, planifica la composición, elige el esquema de color, etc.

El estado completo de este proceso de razonamiento se comprime y cifra en thoughtSignature. Cuando realizas una edición de imagen en una conversación de varias rondas (por ejemplo, "cambia el fondo a azul"), el modelo necesita recuperar el estado de razonamiento anterior para comprender con precisión tu intención de modificación.

Si no devuelves thoughtSignature:

• Escenarios de solo texto: No hay error, pero la calidad del razonamiento y la coherencia disminuirán.
• Escenarios de llamada a herramientas/funciones: Se devuelve directamente un error HTTP 400.
• Conversaciones de edición de imágenes: Es probable que se pierda el contexto y los resultados de la edición sean imprecisos.

🎯 Consejo de desarrollo: En cualquier escenario de conversación de varias rondas, debes conservar y devolver thoughtSignature íntegramente. Al realizar la invocación del modelo a través de APIYI (apiyi.com), la plataforma gestiona automáticamente la transferencia de firmas y la compatibilidad de formatos, por lo que no necesitas gestionarlo manualmente.

Cómo manejar correctamente thoughtSignature en la API de Nano Banana 2

Ejemplo minimalista: extraer correctamente la respuesta y distinguir entre imágenes y firmas

El siguiente código muestra cómo extraer correctamente la imagen de la respuesta de Nano Banana 2 y, al mismo tiempo, guardar thoughtSignature para su uso posterior:

from google import genai
from google.genai import types

client = genai.Client(api_key="TU_CLAVE_API")

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Dibuja un gato blanco bajo un cerezo"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
        thinking_config=types.ThinkingConfig(
            include_thoughts=True
        ),
    )
)

saved_signature = None
for part in response.parts:
    if hasattr(part, 'thought') and part.thought:
        print(f"Proceso de pensamiento: {part.text[:100]}...")
    elif hasattr(part, 'thought_signature') and part.thought_signature:
        saved_signature = part.thought_signature  # ¡Guardar, no decodificar!
        print("thoughtSignature guardada (no es una imagen)")
    elif image := part.as_image():
        image.save("gato_cerezo.png", format="PNG")
        print("Imagen guardada")

from google import genai
from google.genai import types

client = genai.Client(api_key="TU_CLAVE_API")

# Primera ronda: generar imagen
response1 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Dibuja un gato blanco bajo un cerezo"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
        thinking_config=types.ThinkingConfig(
            include_thoughts=True
        ),
    )
)

# Extraer imagen y firma
image_data = None
thought_signature = None
model_parts = []

for part in response1.parts:
    model_parts.append(part)  # Conservar las partes completas
    if hasattr(part, 'thought_signature') and part.thought_signature:
        thought_signature = part.thought_signature
    elif image := part.as_image():
        image.save("ronda1.png", format="PNG")

# Segunda ronda: editar basándose en el resultado anterior
# Clave: pasar las partes completas de la ronda anterior (incluyendo thoughtSignature) como historial
history = [
    {"role": "user", "parts": [{"text": "Dibuja un gato blanco bajo un cerezo"}]},
    {"role": "model", "parts": model_parts},  # Contiene thoughtSignature
]

response2 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=history + [
        {"role": "user", "parts": [{"text": "Cambia el fondo a un cielo nocturno y añade una luna"}]}
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
    )
)

for part in response2.parts:
    if image := part.as_image():
        image.save("ronda2_editada.png", format="PNG")
        print("Imagen editada guardada")

Consejo: Al invocar Nano Banana 2 a través de APIYI (apiyi.com), la plataforma ofrece una interfaz compatible con el formato de OpenAI que gestiona automáticamente la transferencia de thoughtSignature, eliminando la necesidad de gestionar manualmente el estado de la firma en conversaciones de varias rondas.

Errores comunes y soluciones para thoughtSignature en la API de Nano Banana 2

Resumen de escenarios de error

Equivalencia de nombres de campo para thoughtSignature en la API de Nano Banana 2

Los nombres de los campos varían según el método de invocación, lo cual suele causar confusiones:

Solución de emergencia para la API de Nano Banana 2: firma dummy

Si estás migrando un historial de chat antiguo y no tienes una thoughtSignature válida, Google proporciona un valor especial para omitir la validación:

DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

Pasar esta cadena como valor de thoughtSignature evitará el error 400. Sin embargo, es solo una solución de emergencia, ya que la coherencia del razonamiento del modelo se verá afectada.

🎯 Buenas prácticas: Guarda todas las thoughtSignature desde la primera invocación para mantener una cadena de historial de chat correcta.
Si la gestión manual te parece compleja, usar la interfaz compatible con OpenAI a través de APIYI (apiyi.com) puede simplificar enormemente el proceso.

Preguntas frecuentes

Resumen

Puntos clave sobre thoughtSignature en la API de Nano Banana 2:

1. No es una imagen: thoughtSignature es una firma cifrada del proceso de pensamiento, no datos de imagen en base64, por lo que no puede decodificarse en ningún formato de imagen.
2. Debe devolverse tal cual: En conversaciones multironda, debes guardar y devolver la thoughtSignature sin cambios; de lo contrario, la invocación del modelo dará un error 400 y la calidad del texto disminuirá.
3. Distinción correcta de los tres tipos de partes: Las que tienen inlineData son imágenes, las que tienen thoughtSignature son firmas y las que tienen thought: true son resúmenes de pensamiento.

Al comprender la naturaleza de este campo, evitarás caer en el error común de intentar decodificar la firma como si fuera una imagen al procesar las respuestas de la API de Nano Banana 2.

Te recomendamos utilizar APIYI (apiyi.com) para verificar rápidamente la función de edición de imágenes multironda de Nano Banana 2; la plataforma gestiona automáticamente la transmisión de thoughtSignature, ofrece cuotas gratuitas y una interfaz unificada.

📚 Referencias

1. Documentación oficial de Thought Signatures: Explicación completa de Google sobre el mecanismo thoughtSignature.

   • Enlace: ai.google.dev/gemini-api/docs/thought-signatures
   • Descripción: Incluye definiciones de campos, reglas de transferencia y ejemplos de conversaciones de múltiples turnos.

2. Documentación del modo Thinking de Gemini: Cómo activar la función Thinking y sus parámetros de configuración.

   • Enlace: ai.google.dev/gemini-api/docs/thinking
   • Descripción: Aprende sobre configuraciones como include_thoughts, thinking_level, entre otras.

3. Referencia de la API de inferencia de Vertex AI: Definición completa de los campos del objeto Part en la API REST.

   • Enlace: docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference
   • Descripción: Incluye definiciones de tipo y restricciones de uso para thoughtSignature.

4. Centro de documentación de APIYI: Solución simplificada para invocar Nano Banana 2 a través de una interfaz compatible con OpenAI.

   • Enlace: docs.apiyi.com
   • Descripción: Gestiona automáticamente la transferencia de thoughtSignature, reduciendo la complejidad del desarrollo.

Autor: Equipo técnico de APIYI
Intercambio técnico: Te invitamos a participar en la sección de comentarios. Para más información, visita el centro de documentación de APIYI en docs.apiyi.com.