Note de l'auteur : Vous rencontrez l'erreur « Image part is missing a thought_signature » avec Nano Banana 2 ? Il s'agit d'une erreur 400 causée par l'absence de renvoi de la signature de réflexion lors de conversations multi-tours. Cet article détaille les causes, les solutions et propose des exemples de code.
Si vous recevez ce message d'erreur lors de l'édition d'images avec 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."
}
}
Pas de panique, il s'agit d'une exigence du mécanisme de conversation multi-tours de la série Gemini 3, et non d'un problème de sécurité ou d'une panne de plateforme. Pour faire simple : vous avez envoyé une image précédemment générée dans la deuxième requête, mais sans inclure son thought_signature (signature de réflexion).
Valeur ajoutée : Après avoir lu cet article, vous comprendrez le fonctionnement du thought_signature, maîtriserez 3 solutions de correction et apprendrez à gérer correctement les signatures de réflexion dans les scénarios d'édition d'images multi-tours.
Analyse approfondie de l'erreur thought_signature dans Nano Banana 2
Que signifie réellement cette erreur ?
Décomposons ce message d'erreur point par point :
| Champ | Signification | Explication |
|---|---|---|
| status_code: 400 | Erreur de paramètres de requête | Ce n'est pas une erreur serveur, mais un problème de paramètres côté client |
| Image part | Données d'image incluses dans la requête | Vous avez envoyé une image lors de la 2ème requête |
| missing a thought_signature | Signature de réflexion manquante | Cette image a été générée au tour précédent et nécessite une signature associée |
| content position 2, part position 1 | 2ème message de l'historique, 1er élément | Localisation précise de la signature manquante |
En résumé : L'API Gemini est sans état (stateless). Le modèle utilise la thought_signature (signature de réflexion) pour maintenir le contexte de raisonnement entre les tours de conversation. Lorsque vous lancez une deuxième requête d'édition d'image, vous devez renvoyer la thought_signature renvoyée par le modèle au tour précédent, sinon vous recevrez une erreur 400.
Pourquoi la série Gemini 3 impose-t-elle la thought_signature ?
| Comparaison | Série Gemini 2.x | Série Gemini 3 (incluant NB2) |
|---|---|---|
| Signature de réflexion | Optionnelle dans certains cas | Obligatoire pour tous les types de "part" |
| Rigueur de validation | Souple | Stricte (erreur 400 si absente) |
| Portée | Principalement pour les appels de fonction | Texte, images, appels de fonction : tout est concerné |
| Gestion automatique | SDK officiel géré | SDK officiel géré |
La série Gemini 3 (dont le modèle gemini-3.1-flash sur lequel repose Nano Banana 2) impose cette signature pour les raisons suivantes :
- Restauration de l'état de raisonnement : La signature est une représentation chiffrée du processus de réflexion interne, permettant au modèle de retrouver son « état de pensée » lors du tour suivant.
- Continuité de l'édition d'image : Pour les éditions multi-tours, le modèle doit comprendre que « cette image a été générée par moi à l'étape précédente » pour exécuter correctement les instructions.
- Sécurité et cohérence : Le mécanisme de signature garantit que l'historique de la conversation n'a pas été altéré, renforçant la fiabilité des interactions.
🎯 Point clé : Cette erreur 400 n'a absolument rien à voir avec les politiques de sécurité du contenu (IMAGE_SAFETY) et n'est pas un problème lié à la plateforme APIYI. Il s'agit d'une exigence mécanique normale des modèles Gemini 3, qui doit être gérée au niveau du code.
3 solutions pour corriger l'erreur thought_signature dans Nano Banana 2
Solution 1 : Utiliser la fonction chat du SDK officiel (Recommandé)
Si vous utilisez le SDK officiel de Google (Python / Node.js / Java), la méthode la plus simple consiste à utiliser la fonction chat. Le SDK gérera automatiquement la thought_signature :
from google import genai
client = genai.Client(api_key="VOTRE_CLE_API")
# Utilisation de la fonction chat, le SDK gère automatiquement la thought_signature
chat = client.chats.create(model="gemini-3.1-flash-image-preview")
# 1er tour : Génération d'image
response1 = chat.send_message("Dessine un chat orange assis sur un rebord de fenêtre")
# 2ème tour : Édition d'image (la signature est renvoyée automatiquement)
response2 = chat.send_message("Ajoute un bonnet de Noël au chat")
Solution 2 : Extraire et renvoyer manuellement la thought_signature
Si vous utilisez des appels HTTP personnalisés ou une interface compatible OpenAI, vous devez gérer la signature manuellement. La logique clé est la suivante : extraire la thought_signature de la réponse précédente et l'inclure telle quelle dans la partie correspondante de la requête suivante.
import openai
client = openai.OpenAI(
api_key="VOTRE_CLE_API",
base_url="https://vip.apiyi.com/v1"
)
# 1er tour : Génération d'image
response1 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[{"role": "user", "content": "Dessine un chat orange"}]
)
# Clé : Sauvegarder la réponse complète du modèle
# Incluant les données d'image et la thought_signature
model_reply = response1.choices[0].message
# 2ème tour : Édition d'image
# Transmettre la réponse complète du modèle comme historique de conversation
response2 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[
{"role": "user", "content": "Dessine un chat orange"},
model_reply, # Renvoyer l'intégralité, incluant la thought_signature
{"role": "user", "content": "Ajoute un bonnet au chat"}
]
)
Solution 3 : Passer à des requêtes à tour unique
Si votre scénario ne nécessite pas d'édition multi-tours, vous pouvez envoyer des requêtes indépendantes à chaque fois, évitant ainsi totalement le problème de la thought_signature :
# Édition d'image à tour unique : transmettre directement l'image originale + instruction d'édition
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": "Ajoute un bonnet de Noël à ce chat"}
]
}]
)
🎯 Recommandation : Pour les nouveaux projets, nous conseillons la solution 1 (fonction
chatdu SDK officiel). Pour les projets existants, choisissez la solution 2 ou 3 selon l'ampleur des modifications. Lors de l'invocation de Nano Banana 2 via la plateforme APIYI (apiyi.com), les solutions 2 et 3 fonctionnent parfaitement.
Idées reçues sur le thought_signature de Nano Banana 2
| Idée reçue | Réalité |
|---|---|
| C'est un problème de sécurité du contenu | Non. L'erreur 400 indique un échec de validation des paramètres, sans lien avec IMAGE_SAFETY |
| C'est un problème de la plateforme API | Non. Il s'agit d'une exigence mécanique des modèles de la série Gemini 3 |
| Je peux construire la signature moi-même | Impossible. La signature est chiffrée, vous devez renvoyer la valeur retournée par le modèle telle quelle |
| Seuls les appels de fonction en ont besoin | Tous les types de "part" de la série Gemini 3 peuvent en avoir besoin |
Désactiver thinking: off permet de l'éviter |
Non. Même si le niveau de réflexion est réglé sur minimal, la signature sera toujours renvoyée et devra être renvoyée |
Emplacement du thought_signature dans la réponse de Nano Banana 2
Dans les données de réponse de Nano Banana 2, il faut prêter attention à deux types de "part" spécifiques :
Images temporaires (thought: true) : Images intermédiaires générées pendant le processus de réflexion du modèle, marquées avec thought: true. Ce sont des données temporaires qui n'ont pas besoin d'être affichées à l'utilisateur.
Image finale (avec thought_signature) : L'image générée finale contiendra un champ thought_signature. C'est la signature que vous devez renvoyer lors de la prochaine requête.
{
"candidates": [{
"content": {
"parts": [
{
"inlineData": {"mimeType": "image/png", "data": "..."},
"thought_signature": "CkYKRAo..."
}
]
}
}]
}
🎯 Détails techniques :
thought_signatureest une chaîne chiffrée, dont la longueur se situe généralement entre 200 et 500 caractères. N'essayez pas de l'analyser, de la modifier ou de la construire vous-même : renvoyez exactement ce que vous avez reçu. Lors d'une invocation du modèle via APIYI (apiyi.com), le format de réponse est strictement identique à celui de l'API native de Google.
Liste de vérification pour les erreurs de thought_signature sur Nano Banana 2
4 étapes de dépannage rapide :
- Confirmez s'il s'agit de requêtes multi-tours : Si votre tableau
messagescontient les réponses précédentes du rôlemodel(en particulier les données d'image), il s'agit d'une requête multi-tours. - Vérifiez si la réponse complète a été enregistrée : La réponse retournée par le modèle lors du tour précédent contient-elle le champ
thought_signature? A-t-elle été enregistrée intégralement ? - Vérifiez si la signature a été modifiée : Lors de la sérialisation/désérialisation JSON, la chaîne de signature a-t-elle été tronquée ou échappée ?
- Vérifiez l'alignement de la position du "part" : Le message d'erreur
content position X, part position Ypeut vous aider à localiser précisément quel "part" manque de signature.
FAQ
Q1 : Est-ce que la génération d’images en une seule étape peut aussi provoquer cette erreur ?
Généralement non. L'erreur thought_signature survient presque exclusivement lors de conversations multi-tours, lorsque vous réinjectez dans l'historique de la conversation les images renvoyées précédemment par le modèle pour envoyer une nouvelle requête. La génération d'images en une seule étape (texte vers image ou image vers image en envoyant directement l'image originale) n'implique pas d'historique de conversation et ne nécessite donc pas de gestion de signature.
Q2 : Comment gérer cela lors d’une invocation via l’interface compatible OpenAI ?
Lorsque vous invoquez Nano Banana 2 via l'interface compatible OpenAI d'APIYI (apiyi.com), l'essentiel est de conserver l'objet complet de la réponse du modèle de la phase précédente et de le transmettre comme historique de conversation lors de la requête suivante. Ne vous contentez pas de sauvegarder les données d'image en supprimant les autres champs. Si votre framework (comme Dify ou Cherry Studio) gère automatiquement l'historique de la conversation, vérifiez s'il conserve bien l'intégralité du thought_signature.
Q3 : Faut-il renvoyer les images temporaires marquées `thought: true` ?
Oui. Nano Banana 2 peut renvoyer des images temporaires marquées thought: true pendant le processus d'inférence ; elles font partie du « processus de réflexion » du modèle. Lors de la construction de l'historique de la conversation, toutes les parties (parts) renvoyées par le modèle, y compris les images temporaires, doivent être renvoyées intégralement. La méthode la plus sûre consiste à renvoyer directement l'objet de réponse complet du modèle.
Résumé
Points clés concernant l'erreur 400 thought_signature de Nano Banana 2 :
- Ce n'est pas un problème de sécurité du contenu : Il s'agit d'une exigence du mécanisme de conversation multi-tours des modèles de la série Gemini 3, sans lien avec
IMAGE_SAFETY. - Cause identifiée : Lors de requêtes multi-tours, le
thought_signaturerenvoyé par le modèle lors de la phase précédente n'a pas été renvoyé tel quel. - Solution : Utilisez la fonction de chat du SDK officiel (qui gère cela automatiquement), extrayez et renvoyez manuellement la signature, ou passez à des requêtes en une seule étape.
Gardez à l'esprit le principe fondamental : ne modifiez pas, ne supprimez pas et ne construisez pas vous-même le thought_signature renvoyé par le modèle — renvoyez exactement ce que vous avez reçu.
Si vous avez besoin d'invoquer Nano Banana 2 via une plateforme tierce, nous vous recommandons APIYI (apiyi.com). Le format de réponse est strictement identique à l'API native de Google, au tarif de 0,05 $ par requête, sans limite de concurrence.
📚 Références
-
Documentation officielle de Google sur les Thought Signatures : Analyse détaillée du mécanisme de signature de pensée
- Lien :
ai.google.dev/gemini-api/docs/thought-signatures - Description : Documentation officielle incluant le fonctionnement, le comportement du modèle et la gestion via le SDK.
- Lien :
-
Guide du développeur Google Gemini 3 : Nouvelles fonctionnalités de la série Gemini 3
- Lien :
ai.google.dev/gemini-api/docs/gemini-3 - Description : Exigences de signature obligatoire et présentation des nouvelles fonctionnalités de la série Gemini 3.
- Lien :
-
Documentation Google sur la génération d'images : Bonnes pratiques pour la génération d'images Nano Banana
- Lien :
ai.google.dev/gemini-api/docs/image-generation - Description : Conseils d'utilisation de
thought_signaturepour l'édition d'images multi-tours.
- Lien :
-
Documentation Google Cloud Vertex AI : Explications sur la signature de pensée en entreprise
- Lien :
docs.google.com/vertex-ai/generative-ai/docs/thought-signatures - Description : Méthodes de configuration et de traitement des signatures dans l'environnement Vertex AI.
- Lien :
Auteur : Équipe technique APIYI
Échanges techniques : N'hésitez pas à discuter de vos retours d'expérience sur l'implémentation de l'édition multi-tours avec Nano Banana 2 dans les commentaires. Pour plus d'informations, consultez le centre de documentation APIYI sur docs.apiyi.com.
