Interprétation du thoughtSignature de l’API Nano Banana 2 : pourquoi le décodage base64 ne donne-t-il pas une image ?

Note de l'auteur : Analyse approfondie de la nature du champ thoughtSignature dans les réponses de l'API Nano Banana 2 : il ne s'agit pas d'une image, mais d'une signature de réflexion chiffrée. Explications détaillées sur la structure de réponse en mode "Thinking", la bonne manière de la traiter et les pièges courants.

De nombreux développeurs, en utilisant l'API Nano Banana 2 pour générer des images, remarquent qu'en plus des données d'image, la réponse contient un champ thoughtSignature. Il s'agit d'une longue chaîne encodée en base64 qui ressemble à s'y méprendre à des données d'image. Après avoir tenté de la décoder, on se rend compte qu'il est impossible d'en faire une image. Qu'est-ce que c'est exactement ? Cet article explique en détail la nature de thoughtSignature, pourquoi ce n'est pas une image et comment le gérer correctement lors de conversations multi-tours.

Valeur ajoutée : Après avoir lu cet article, vous comprendrez les principes techniques de thoughtSignature, éviterez de le traiter par erreur comme une image et maîtriserez la méthode pour transmettre correctement cette signature lors de vos échanges.

Points clés sur thoughtSignature de l'API Nano Banana 2

Répondons d'abord à la question la plus fréquente : thoughtSignature n'est pas une image, il ne peut pas être décodé en tant que tel. Il s'agit de la signature chiffrée du processus de réflexion du modèle.

À quoi ressemble thoughtSignature dans la réponse de l'API Nano Banana 2 ?

Lorsque vous appelez Nano Banana 2 pour générer une image, le tableau parts dans la réponse de l'API peut contenir plusieurs éléments. Voici une structure de réponse typique :

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "Laissez-moi réfléchir à la manière de générer cette image...",
          "thought": true
        },
        {
          "text": "",
          "thoughtSignature": "CpcHAdHtim9+q4rstcbvQC0ic4x1/vqQlCJ..."
        },
        {
          "inlineData": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUg..."
          }
        }
      ]
    }
  }]
}

Il y a ici trois part distincts :

1. Résumé de la réflexion (thought: true) : Aperçu textuel du processus de raisonnement du modèle.
2. Signature de réflexion (thoughtSignature) : Instantané chiffré de l'état de raisonnement.
3. Données d'image (inlineData) : Les données réelles de l'image en base64.

Le problème crucial est que les 2ème et 3ème parties contiennent toutes deux des données encodées en base64. Si votre code ne les distingue pas correctement, il essaiera de décoder thoughtSignature comme s'il s'agissait d'une image, et vous constaterez qu'il est impossible de l'afficher.

title: "Principes techniques de thoughtSignature dans l'API Nano Banana 2"
description: "Comprenez le rôle crucial de thoughtSignature dans l'API Nano Banana 2 pour maintenir la cohérence du raisonnement lors de la génération d'images."

Principes techniques de thoughtSignature dans l'API Nano Banana 2

Maintenant que nous avons compris que thoughtSignature n'est pas une image, examinons ce qu'il est réellement.

L'essence de thoughtSignature

Selon la définition officielle de Google :

thoughtSignature (chaîne de caractères, optionnel) : "Une signature opaque pour la pensée afin qu'elle puisse être réutilisée dans les requêtes ultérieures. Une chaîne encodée en base64."

Pour faire simple : thoughtSignature est un "instantané de mémoire" du processus de réflexion du modèle, renvoyé sous forme de chaîne base64 après signature cryptographique. Son rôle est de permettre au modèle de "se souvenir" du processus de raisonnement précédent lors de conversations multi-tours, assurant ainsi la cohérence de sa réflexion.

Quelques caractéristiques clés :

• Opaque : Les développeurs ne peuvent pas interpréter son contenu et n'ont pas besoin de se soucier de sa structure interne.
• Signature cryptographique : Signée par le serveur Google, elle est infalsifiable — transmettre une chaîne base64 aléatoire renverra une erreur de "signature invalide".
• Avec état (Stateful) : Contient la chaîne de raisonnement et les résultats des calculs intermédiaires du modèle lors de la génération de la réponse actuelle.

Différence entre thoughtSignature et thought

Ces deux champs sont souvent confondus, mais ils sont totalement différents :

thought est un résumé de raisonnement destiné à l'utilisateur, tandis que thoughtSignature est une mémoire de raisonnement destinée au modèle.

Pourquoi l'API Nano Banana 2 a-t-elle besoin de thoughtSignature ?

Nano Banana 2 appartient à la série Gemini 3.1 et prend en charge le mode Thinking (réflexion). Avant de générer une image, le modèle effectue un raisonnement interne : analyse de l'intention de l'invite, planification de la composition, choix de la palette de couleurs, etc.

L'état complet de ce processus de raisonnement est compressé et chiffré dans thoughtSignature. Lorsque vous effectuez une édition d'image dans une conversation multi-tours (par exemple, "change le fond en bleu"), le modèle doit restaurer l'état de raisonnement précédent pour comprendre précisément votre intention de modification.

Si vous ne renvoyez pas thoughtSignature :

• Scénarios purement textuels : pas d'erreur, mais la qualité et la cohérence du raisonnement diminueront.
• Scénarios d'appel d'outils/fonctions : renvoie directement une erreur HTTP 400.
• Conversations multi-tours d'édition d'image : risque de perte de contexte, rendant les résultats d'édition imprécis.

🎯 Conseil de développement : Dans tout scénario de conversation multi-tours, vous devez conserver et renvoyer intégralement thoughtSignature.
Lors d'une invocation du modèle via APIYI (apiyi.com), la plateforme gère automatiquement la transmission de la signature et la compatibilité des formats, sans que le développeur n'ait à le gérer manuellement.

Comment traiter correctement thoughtSignature dans l'API Nano Banana 2

Exemple minimal : analyser correctement la réponse et distinguer l'image de la signature

Le code suivant montre comment extraire correctement l'image de la réponse de Nano Banana 2, tout en enregistrant thoughtSignature pour une utilisation ultérieure :

from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Dessine un chat blanc sous un cerisier"],
    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"Processus de réflexion: {part.text[:100]}...")
    elif hasattr(part, 'thought_signature') and part.thought_signature:
        saved_signature = part.thought_signature  # Sauvegarder, ne pas décoder !
        print("thoughtSignature sauvegardé (pas une image)")
    elif image := part.as_image():
        image.save("chat_cerisier.png", format="PNG")
        print("Image sauvegardée")

from google import genai
from google.genai import types

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

# Premier tour : générer l'image
response1 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Dessine un chat blanc sous un cerisier"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
        thinking_config=types.ThinkingConfig(
            include_thoughts=True
        ),
    )
)

# Extraire l'image et la signature
image_data = None
thought_signature = None
model_parts = []

for part in response1.parts:
    model_parts.append(part)  # Conserver les parts complètes
    if hasattr(part, 'thought_signature') and part.thought_signature:
        thought_signature = part.thought_signature
    elif image := part.as_image():
        image.save("tour1.png", format="PNG")

# Deuxième tour : édition basée sur le résultat précédent
# Clé : transmettre les parts complètes du tour précédent (incluant thoughtSignature) comme historique
history = [
    {"role": "user", "parts": [{"text": "Dessine un chat blanc sous un cerisier"}]},
    {"role": "model", "parts": model_parts},  # Contient thoughtSignature
]

response2 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=history + [
        {"role": "user", "parts": [{"text": "Change le fond pour un ciel nocturne avec une lune"}]}
    ],
    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("tour2_edite.png", format="PNG")
        print("Image éditée sauvegardée")

Conseil : Lors de l'invocation de Nano Banana 2 via APIYI (apiyi.com), la plateforme fournit une interface compatible avec le format OpenAI, gérant automatiquement la transmission de thoughtSignature sans nécessiter de gestion manuelle de l'état de la signature dans les conversations multi-tours.

Voici un guide pratique pour éviter les pièges courants liés au champ thoughtSignature de l'API Nano Banana 2.

Résumé des scénarios problématiques

Correspondance des noms de champs pour Nano Banana 2

Les noms de champs varient selon la méthode d'appel, ce qui est une source fréquente d'erreurs :

Solution d'urgence pour Nano Banana 2 : la signature "dummy"

Si vous migrez un historique de conversation ancien sans thoughtSignature valide, Google propose une valeur de contournement :

DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

Utiliser cette chaîne comme valeur pour thoughtSignature permet d'éviter l'erreur 400. Notez qu'il s'agit d'une solution de secours et que la cohérence du raisonnement du modèle peut en être affectée.

🎯 Bonnes pratiques : Enregistrez systématiquement tous les thoughtSignature dès le premier appel pour maintenir une chaîne d'historique correcte.
Si la gestion manuelle vous semble complexe, l'utilisation d'une interface compatible OpenAI via APIYI (apiyi.com) permet de simplifier considérablement le processus.

FAQ

Résumé

Points clés concernant thoughtSignature dans l'API Nano Banana 2 :

1. Ce n'est pas une image : thoughtSignature est une signature chiffrée du processus de réflexion, pas une donnée d'image base64 ; elle ne peut être décodée en aucun format d'image.
2. Doit être renvoyée telle quelle : Vous devez enregistrer et renvoyer la thoughtSignature telle quelle lors des conversations multi-tours, sous peine d'erreurs 400 lors de l'invocation du modèle et d'une baisse de qualité des réponses textuelles.
3. Distinction correcte des trois types de parties : Celles avec inlineData sont des images, celles avec thoughtSignature sont des signatures, et celles avec thought: true sont des résumés de réflexion.

En comprenant la nature de ce champ, vous éviterez le piège classique consistant à essayer de décoder une signature comme s'il s'agissait d'une image lors de l'analyse des réponses de l'API Nano Banana 2.

Nous vous recommandons d'utiliser APIYI (apiyi.com) pour tester rapidement les fonctionnalités d'édition d'image multi-tours de Nano Banana 2. La plateforme gère automatiquement la transmission de la thoughtSignature, offre des crédits gratuits et propose une interface unifiée.

📚 Références

1. Documentation officielle de Thought Signatures : Explication complète de Google sur le mécanisme thoughtSignature

   • Lien : ai.google.dev/gemini-api/docs/thought-signatures
   • Description : Inclut les définitions de champs, les règles de transmission et des exemples de conversations multi-tours.

2. Documentation du mode Thinking de Gemini : Comment activer la fonctionnalité Thinking et configurer ses paramètres

   • Lien : ai.google.dev/gemini-api/docs/thinking
   • Description : Découvrez les configurations telles que include_thoughts et thinking_level.

3. Référence de l'API d'inférence Vertex AI : Définition complète des champs de l'objet Part dans l'API REST

   • Lien : docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference
   • Description : Inclut la définition du type et les restrictions d'utilisation de thoughtSignature.

4. Centre de documentation APIYI : Solution simplifiée pour invoquer Nano Banana 2 via une interface compatible OpenAI

   • Lien : docs.apiyi.com
   • Description : Gère automatiquement la transmission de thoughtSignature pour réduire la complexité du développement.

Auteur : Équipe technique APIYI
Échanges techniques : N'hésitez pas à discuter dans la section commentaires. Pour plus d'informations, visitez le centre de documentation APIYI sur docs.apiyi.com.