Nota del autor: ¿Te aparece el error "Image part is missing a thought_signature" en Nano Banana 2? Esto se debe a que no se ha devuelto la firma de pensamiento durante una conversación de varias rondas, lo que provoca un error 400. En este artículo, explicamos detalladamente la causa, las soluciones y ejemplos de código.
Si recibes este error al editar imágenes con Nano Banana 2 (gemini-3.1-flash-image-preview):
{
"status_code": 400,
"error": {
"message": "Image part is missing a thought_signature in content position 2, part position 1."
}
}
No entres en pánico: esto es un requisito del mecanismo de conversación de varias rondas de la serie Gemini 3, no un problema de seguridad de contenido ni un fallo de la plataforma. En pocas palabras: enviaste una imagen generada previamente en la segunda ronda de la solicitud, pero no incluiste su thought_signature (firma de pensamiento).
Valor principal: Al terminar de leer este artículo, entenderás cómo funciona la thought_signature, dominarás 3 soluciones y aprenderás a gestionar correctamente la firma de pensamiento en escenarios de edición de imágenes de varias rondas.
Interpretación esencial del error thought_signature en Nano Banana 2
¿Qué significa realmente este error?
Desglosemos este mensaje de error palabra por palabra:
| Campo | Significado | Explicación |
|---|---|---|
| status_code: 400 | Error de parámetros de solicitud | No es un error del servidor, sino un problema con los parámetros enviados por el cliente |
| Image part | Datos de imagen incluidos en la solicitud | Enviaste una imagen en la segunda ronda de la solicitud |
| missing a thought_signature | Falta la firma de pensamiento | Esta imagen fue generada por el modelo en la ronda anterior y requiere una firma adjunta |
| content position 2, part position 1 | En el segundo mensaje del historial (respuesta del modelo), primer part | Ubicación exacta donde falta la firma |
Resumen en una frase: La API de Gemini es apátrida (stateless), y el modelo utiliza thought_signature (firma de pensamiento) para mantener el contexto de razonamiento entre múltiples rondas de diálogo. Cuando inicias una segunda ronda de solicitud de edición de imagen, debes devolver la thought_signature que el modelo devolvió en la ronda anterior tal cual, de lo contrario recibirás un error 400.
¿Por qué la serie Gemini 3 exige obligatoriamente thought_signature?
| Comparativa | Serie Gemini 2.x | Serie Gemini 3 (incl. NB2) |
|---|---|---|
| Firma de pensamiento | Opcional en algunos escenarios | Obligatoria en todos los tipos de part |
| Rigurosidad de validación | Flexible | Estricta (error 400 si falta) |
| Alcance | Principalmente para llamadas a funciones | Aplicable a texto, imágenes y funciones |
| Gestión automática | SDK oficial la gestiona | SDK oficial la gestiona |
La serie de modelos Gemini 3 (incluyendo gemini-3.1-flash, en la que se basa Nano Banana 2) exige la firma de pensamiento porque:
- Recuperación del estado de razonamiento: La firma de pensamiento es una representación cifrada del proceso de razonamiento interno del modelo, lo que permite que el modelo recupere su "estado de pensamiento" previo en la siguiente ronda.
- Continuidad en la edición de imágenes: Para ediciones de imágenes en varias rondas, el modelo necesita entender que "esta imagen fue generada por mí en el paso anterior" para ejecutar correctamente las instrucciones de edición.
- Seguridad y consistencia: El mecanismo de firma garantiza que el historial del diálogo no haya sido alterado, mejorando la fiabilidad de las interacciones multironda.
🎯 Conclusión clave: Este error 400 no tiene nada que ver con las políticas de seguridad de contenido (IMAGE_SAFETY), ni es un problema de la plataforma APIYI. Es un requisito del mecanismo normal de los modelos de la serie Gemini 3 que debe gestionarse correctamente a nivel de código.
3 soluciones para el error thought_signature en Nano Banana 2
Solución 1: Usar la función chat del SDK oficial (Recomendado)
Si utilizas el SDK oficial de Google (Python / Node.js / Java), la forma más sencilla es usar la función de chat; el SDK gestionará automáticamente la thought_signature:
from google import genai
client = genai.Client(api_key="TU_CLAVE_API")
# Usar la función de chat, el SDK gestiona automáticamente la thought_signature
chat = client.chats.create(model="gemini-3.1-flash-image-preview")
# 1ª ronda: Generar imagen
response1 = chat.send_message("Dibuja un gato naranja sentado en el alféizar de una ventana")
# 2ª ronda: Editar imagen (la firma se devuelve automáticamente)
response2 = chat.send_message("Ponle un gorro de Navidad al gato")
Solución 2: Extraer y devolver manualmente la thought_signature
Si utilizas llamadas HTTP personalizadas o invocas a través de una interfaz compatible con OpenAI, debes gestionar la firma manualmente. La lógica clave es: extraer la thought_signature de la respuesta de la ronda anterior y adjuntarla tal cual en el part correspondiente de la siguiente solicitud.
import openai
client = openai.OpenAI(
api_key="TU_CLAVE_API",
base_url="https://vip.apiyi.com/v1"
)
# 1ª ronda: Generar imagen
response1 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[{"role": "user", "content": "Dibuja un gato naranja"}]
)
# Clave: Guardar la respuesta completa del modelo
# Incluyendo los datos de la imagen y la thought_signature
model_reply = response1.choices[0].message
# 2ª ronda: Editar imagen
# Pasar la respuesta completa del modelo como historial de diálogo
response2 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[
{"role": "user", "content": "Dibuja un gato naranja"},
model_reply, # Devolver completo, incluyendo la thought_signature
{"role": "user", "content": "Ponle un gorro al gato"}
]
)
Solución 3: Cambiar a solicitudes de una sola ronda
Si tu escenario no requiere edición de diálogo multironda, puedes enviar solicitudes independientes de una sola ronda cada vez, evitando por completo el problema de la thought_signature:
# Edición de imagen de una sola ronda: Pasar directamente la imagen original + instrucción de edición
response = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "data:image/png;base64,/9j/..."}},
{"type": "text", "text": "Ponle un gorro de Navidad a este gato"}
]
}]
)
🎯 Recomendación: Para proyectos nuevos, se sugiere la Solución 1 (función chat del SDK oficial). Para proyectos existentes, puedes elegir la Solución 2 o 3 según la cantidad de cambios necesarios. Al invocar Nano Banana 2 a través de APIYI apiyi.com, tanto la Solución 2 como la 3 funcionan correctamente.
Errores comunes sobre thought_signature en Nano Banana 2
| Error común | Realidad |
|---|---|
| Es un problema de seguridad de contenido | No. El error 400 es un fallo en la validación de parámetros, no tiene nada que ver con IMAGE_SAFETY |
| Es un problema de la plataforma API | No. Es un requisito del mecanismo de los modelos de la serie Gemini 3 |
| Puedo construir la firma yo mismo | No. La firma está cifrada; debes devolver el valor exacto que retorna el modelo |
| Solo se necesita para llamadas a funciones | Puede ser necesaria para cualquier tipo de "part" en la serie Gemini 3 |
Configurar thinking: off lo evita |
No. Incluso si el nivel de pensamiento se establece en minimal, la firma se devolverá y deberá devolverse |
Ubicación de thought_signature en la respuesta de Nano Banana 2
En los datos de respuesta de Nano Banana 2, debes prestar atención a dos tipos especiales de "parts":
Imágenes temporales (thought: true): Imágenes intermedias generadas durante el proceso de razonamiento del modelo, marcadas como thought: true. Son datos temporales y no necesitan mostrarse al usuario.
Imagen final (con thought_signature): La imagen generada finalmente contendrá un campo thought_signature. Esta es la firma que debes devolver en la siguiente solicitud.
{
"candidates": [{
"content": {
"parts": [
{
"inlineData": {"mimeType": "image/png", "data": "..."},
"thought_signature": "CkYKRAo..."
}
]
}
}]
}
🎯 Detalles técnicos:
thought_signaturees una cadena cifrada con una longitud que suele oscilar entre 200 y 500 caracteres. No intentes analizarla, modificarla ni construirla tú mismo: devuelve exactamente lo que recibas. Al realizar la invocación del modelo a través de APIYI (apiyi.com), el formato de respuesta es idéntico al de la API nativa de Google.
Lista de verificación para errores de thought_signature en Nano Banana 2
4 pasos para una resolución rápida:
- Confirma si es una solicitud de múltiples turnos: Si tu array
messagescontiene respuestas previas del rolmodel(especialmente datos de imagen), entonces es una solicitud de múltiples turnos. - Comprueba si se guardó la respuesta completa: ¿La respuesta que devolvió el modelo en el turno anterior contiene el campo
thought_signature? ¿Se guardó correctamente? - Comprueba si la firma fue modificada: Durante el proceso de serialización/deserialización JSON, ¿la cadena de la firma fue truncada o escapada?
- Comprueba la alineación de la posición del "part": El mensaje de error
content position X, part position Ypuede ayudarte a localizar con precisión qué "part" carece de la firma.
Preguntas frecuentes
Q1: ¿La generación de imágenes de una sola vuelta también puede causar este error?
Normalmente no. El error thought_signature aparece casi exclusivamente en conversaciones multironda, cuando incluyes imágenes devueltas por el modelo en el historial de la conversación y envías una nueva solicitud. Las tareas de texto a imagen o imagen a imagen de una sola vuelta (donde envías la imagen original directamente) no involucran el historial de conversación, por lo que no requieren gestionar firmas.
Q2: ¿Cómo se maneja esto al realizar la invocación del modelo a través de una interfaz compatible con OpenAI?
Al invocar Nano Banana 2 a través de la interfaz compatible con OpenAI de APIYI (apiyi.com), la clave es guardar el objeto completo de la respuesta del modelo de la ronda anterior y pasarlo como historial de conversación en la siguiente solicitud. No guardes solo los datos de la imagen descartando otros campos. Si tu plataforma (como Dify o Cherry Studio) gestiona el historial de conversación automáticamente, verifica que esté conservando el thought_signature de forma íntegra.
Q3: ¿Es necesario devolver las imágenes temporales con `thought: true`?
Sí, es necesario. Durante el proceso de inferencia, Nano Banana 2 puede devolver imágenes temporales marcadas como thought: true, las cuales forman parte del "proceso de pensamiento" del modelo. Al construir el historial de la conversación, todas las partes devueltas por el modelo (incluyendo las imágenes temporales) deben devolverse completas. La forma más segura es devolver directamente el objeto de respuesta completo del modelo.
Resumen
Puntos clave sobre el error 400 de thought_signature en Nano Banana 2:
- No es un problema de seguridad de contenido: Es un requisito del mecanismo de conversación multironda de la serie de modelos Gemini 3, no tiene relación con
IMAGE_SAFETY. - Causa clara: Al realizar solicitudes multironda, no se devolvió el
thought_signatureoriginal que el modelo proporcionó en la ronda anterior. - Solución: Utiliza la función de chat del SDK oficial (que lo gestiona automáticamente), extrae y devuelve la firma manualmente, o cambia a solicitudes de una sola vuelta.
Recuerda el principio fundamental: no modifiques, no descartes y no intentes construir tú mismo el thought_signature devuelto por el modelo; simplemente devuelve exactamente lo que recibiste.
Si necesitas invocar Nano Banana 2 a través de una plataforma de terceros, te recomendamos usar APIYI (apiyi.com), cuyo formato de respuesta es totalmente coherente con la API nativa de Google, con un coste de $0.05 por solicitud y sin límites de concurrencia.
📚 Referencias
-
Documentación oficial de Google sobre Thought Signatures: Explicación detallada del mecanismo de firmas de pensamiento.
- Enlace:
ai.google.dev/gemini-api/docs/thought-signatures - Descripción: Documentación oficial que incluye el principio de funcionamiento, el comportamiento del modelo y cómo lo gestiona el SDK.
- Enlace:
-
Guía para desarrolladores de Google Gemini 3: Nuevas características de la serie Gemini 3.
- Enlace:
ai.google.dev/gemini-api/docs/gemini-3 - Descripción: Explicación de los requisitos de firma obligatorios y las nuevas funciones de la serie Gemini 3.
- Enlace:
-
Documentación de generación de imágenes de Google: Mejores prácticas para la generación de imágenes con Nano Banana.
- Enlace:
ai.google.dev/gemini-api/docs/image-generation - Descripción: Recomendaciones sobre el uso de
thought_signatureen la edición de imágenes multironda.
- Enlace:
-
Documentación de Google Cloud Vertex AI: Explicación de las firmas de pensamiento a nivel empresarial.
- Enlace:
docs.google.com/vertex-ai/generative-ai/docs/thought-signatures - Descripción: Métodos de configuración y gestión de firmas en el entorno de Vertex AI.
- Enlace:
Autor: Equipo técnico de APIYI
Intercambio técnico: Te invitamos a comentar tus experiencias sobre la implementación de la edición multironda en Nano Banana 2. Para más información, visita el centro de documentación de APIYI en docs.apiyi.com.
