Interpretation der thoughtSignature der Nano Banana 2 API: Warum ist das Ergebnis nach der base64-Dekodierung kein Bild?

Anmerkung des Autors: Eine tiefgehende Analyse des thoughtSignature-Feldes in der Nano Banana 2 API-Antwort: Es handelt sich nicht um ein Bild, sondern um eine verschlüsselte Denk-Signatur. Wir erläutern die Struktur der Thinking-Modus-Antwort, die korrekte Handhabung und häufige Fallstricke.

Viele Entwickler, die die Nano Banana 2 API für die Bilderzeugung nutzen, bemerken in der Antwort neben den Bilddaten ein Feld namens thoughtSignature. Es handelt sich ebenfalls um eine lange Base64-kodierte Zeichenfolge, die auf den ersten Blick wie Bilddaten aussieht. Versuche, diese zu dekodieren, schlagen jedoch fehl – was genau ist das also? Dieser Artikel klärt das Wesen von thoughtSignature, warum es kein Bild ist und wie man es bei mehrstufigen Dialogen korrekt verarbeitet.

Kernnutzen: Nach dem Lesen dieses Artikels verstehen Sie das technische Prinzip von thoughtSignature, vermeiden Fehlinterpretationen als Bilddaten und beherrschen die korrekte Weitergabe der Signatur in Dialogen.

Nano Banana 2 API thoughtSignature: Kernpunkte

Zuerst die Antwort auf die häufigste Frage vorab: thoughtSignature ist kein Bild und kann nicht als solches dekodiert werden. Es handelt sich um eine kryptografische Signatur des Denkprozesses des Modells.

Wie sieht die thoughtSignature in der Nano Banana 2 API-Antwort aus?

Wenn Sie Nano Banana 2 zur Bilderzeugung aufrufen, kann das parts-Array in der API-Antwort mehrere Elemente enthalten. Eine typische Antwortstruktur sieht so aus:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "Lass mich darüber nachdenken, wie ich dieses Bild generieren kann...",
          "thought": true
        },
        {
          "text": "",
          "thoughtSignature": "CpcHAdHtim9+q4rstcbvQC0ic4x1/vqQlCJ..."
        },
        {
          "inlineData": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUg..."
          }
        }
      ]
    }
  }]
}

Hier gibt es drei parts:

1. Denk-Zusammenfassung (thought: true): Eine textuelle Übersicht des Inferenzprozesses des Modells.
2. Denk-Signatur (thoughtSignature): Ein verschlüsselter Schnappschuss des Inferenzzustands.
3. Bilddaten (inlineData): Die tatsächlichen Base64-Bilddaten.

Das Hauptproblem besteht darin, dass sowohl der zweite als auch der dritte Teil Base64-kodierte Daten enthalten. Wenn Ihr Code nicht korrekt zwischen diesen unterscheidet, wird die thoughtSignature fälschlicherweise als Bild dekodiert – und Sie werden feststellen, dass sie sich nicht in ein Bild umwandeln lässt.

title: "Technische Grundlagen der thoughtSignature der Nano Banana 2 API"

Technische Grundlagen der thoughtSignature der Nano Banana 2 API

Nachdem wir geklärt haben, dass thoughtSignature kein Bild ist, schauen wir uns an, was es eigentlich ist.

Das Wesen von thoughtSignature

Gemäß der offiziellen Google-Dokumentation:

thoughtSignature (string, optional): "Eine undurchsichtige Signatur für den Gedankengang, damit dieser in nachfolgenden Anfragen wiederverwendet werden kann. Ein base64-kodierter String."

Einfach ausgedrückt: thoughtSignature ist ein "Gedächtnis-Schnappschuss" des Denkprozesses des Modells, der kryptografisch signiert und als Base64-String zurückgegeben wird. Seine Aufgabe ist es, dem Modell zu ermöglichen, sich in mehrstufigen Dialogen an den vorherigen Schlussfolgerungsprozess zu "erinnern", um die gedankliche Kohärenz zu wahren.

Wichtige Merkmale:

• Undurchsichtig (Opaque): Entwickler können den Inhalt nicht lesen und müssen sich nicht um die interne Struktur kümmern.
• Kryptografische Signatur: Vom Google-Server signiert und nicht fälschbar – die Übermittlung eines zufälligen Base64-Strings führt zu einem Fehler wegen "ungültiger Signatur".
• Zustandsbehaftet (Stateful): Enthält die Schlussfolgerungskette und Zwischenergebnisse des Modells bei der Generierung der aktuellen Antwort.

Unterschied zwischen thoughtSignature und thought

Diese beiden Felder werden oft verwechselt, sind aber grundlegend verschieden:

thought ist die Schlussfolgerungszusammenfassung für den Menschen, thoughtSignature ist das Schlussfolgerungsgedächtnis für das Modell.

Warum benötigt die Nano Banana 2 API thoughtSignature?

Nano Banana 2 gehört zur Gemini 3.1-Serie und unterstützt den Thinking-Modus. Bevor das Modell ein Bild generiert, führt es interne Schlussfolgerungen durch – es analysiert die Absicht der Eingabeaufforderung, plant die Komposition, wählt Farbschemata usw.

Der vollständige Zustand dieses Schlussfolgerungsprozesses wird komprimiert und als thoughtSignature verschlüsselt. Wenn Sie in einem mehrstufigen Dialog Bilder bearbeiten (z. B. "Ändere den Hintergrund in Blau"), muss das Modell den vorherigen Schlussfolgerungszustand wiederherstellen, um Ihre Änderungsabsicht präzise zu verstehen.

Wenn Sie thoughtSignature nicht zurücksenden:

• Bei reinem Text: Kein Fehler, aber die Qualität und Kohärenz der Schlussfolgerungen sinken.
• Bei Werkzeug- oder Funktionsaufrufen: Direkte Rückgabe eines HTTP 400-Fehlers.
• Bei mehrstufigen Bildbearbeitungsdialogen: Kontextverlust möglich, Bearbeitungsergebnisse sind ungenau.

🎯 Entwickler-Tipp: In jedem Szenario mit mehrstufigen Dialogen sollten Sie thoughtSignature vollständig beibehalten und zurücksenden. Bei der Nutzung über APIYI (apiyi.com) übernimmt die Plattform automatisch die Übertragung der Signatur und die Formatkompatibilität, sodass Entwickler diese nicht manuell verwalten müssen.

Korrekte Handhabung der thoughtSignature in der Nano Banana 2 API

Minimalistisches Beispiel: Korrektes Parsen der Antwort und Unterscheidung zwischen Bild und Signatur

Der folgende Code zeigt, wie Sie Bilder korrekt aus der Nano Banana 2-Antwort extrahieren und gleichzeitig thoughtSignature für die spätere Verwendung speichern:

from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Zeichne eine weiße Katze unter einem Kirschblütenbaum"],
    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"Schlussfolgerungsprozess: {part.text[:100]}...")
    elif hasattr(part, 'thought_signature') and part.thought_signature:
        saved_signature = part.thought_signature  # Speichern, nicht dekodieren!
        print("thoughtSignature gespeichert (kein Bild)")
    elif image := part.as_image():
        image.save("cat_sakura.png", format="PNG")
        print("Bild gespeichert")

from google import genai
from google.genai import types

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

# Erste Runde: Bild generieren
response1 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Zeichne eine weiße Katze unter einem Kirschblütenbaum"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
        thinking_config=types.ThinkingConfig(
            include_thoughts=True
        ),
    )
)

# Bild und Signatur extrahieren
image_data = None
thought_signature = None
model_parts = []

for part in response1.parts:
    model_parts.append(part)  # Vollständige parts beibehalten
    if hasattr(part, 'thought_signature') and part.thought_signature:
        thought_signature = part.thought_signature
    elif image := part.as_image():
        image.save("round1.png", format="PNG")

# Zweite Runde: Bearbeitung basierend auf dem Ergebnis der ersten Runde
# Wichtig: Die vollständigen parts der ersten Runde (inkl. thoughtSignature) als Historie übergeben
history = [
    {"role": "user", "parts": [{"text": "Zeichne eine weiße Katze unter einem Kirschblütenbaum"}]},
    {"role": "model", "parts": model_parts},  # Enthält thoughtSignature
]

response2 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=history + [
        {"role": "user", "parts": [{"text": "Ändere den Hintergrund in einen Nachthimmel und füge einen Mond hinzu"}]}
    ],
    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("round2_edited.png", format="PNG")
        print("Bearbeitetes Bild gespeichert")

Empfehlung: Wenn Sie Nano Banana 2 über APIYI (apiyi.com) aufrufen, bietet die Plattform eine OpenAI-kompatible Schnittstelle, die die Übertragung der thoughtSignature automatisch abwickelt, sodass Sie den Signaturstatus in Dialogen nicht manuell verwalten müssen.

Nano Banana 2 API thoughtSignature: Häufige Fehler und Lösungen

Zusammenfassung der Fehlerquellen

Nano Banana 2 API: Vergleich der Feldnamen für thoughtSignature

Die Feldnamen variieren je nach Aufrufmethode, was oft zu Verwirrung führt:

Nano Banana 2 API Notlösung: Dummy-Signatur

Falls Sie alte Dialogverläufe migrieren und keine gültige thoughtSignature besitzen, stellt Google einen speziellen Umgehungswert bereit:

DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

Wenn Sie diesen String als thoughtSignature übergeben, lassen sich 400-Fehler vermeiden. Dies ist jedoch nur eine Notlösung, da die logische Konsistenz des Modells darunter leiden kann.

🎯 Best Practice: Speichern Sie von Beginn an alle thoughtSignature-Werte, um eine korrekte Historienkette aufzubauen.
Falls Ihnen die manuelle Verwaltung zu komplex ist, können Sie über APIYI (apiyi.com) die OpenAI-kompatible Schnittstelle nutzen, um den Aufwand erheblich zu reduzieren.

Häufig gestellte Fragen

Zusammenfassung

Die Kernpunkte zu thoughtSignature in der Nano Banana 2 API:

1. Kein Bild: thoughtSignature ist eine verschlüsselte Signatur des Denkprozesses, keine Base64-Bilddatei, und kann nicht in ein Bildformat dekodiert werden.
2. Muss unverändert zurückgesendet werden: Speichern und senden Sie thoughtSignature in mehrstufigen Dialogen unverändert zurück, da es sonst zu 400-Fehlern bei Werkzeugaufrufen kommt und die Qualität der Textdialoge sinkt.
3. Korrekte Unterscheidung der drei Part-Typen: Teile mit inlineData sind Bilder, Teile mit thoughtSignature sind Signaturen und Teile mit thought: true sind Zusammenfassungen der Überlegungen.

Wenn Sie die Natur dieses Feldes verstehen, vermeiden Sie bei der Analyse der Nano Banana 2 API-Antworten den Fehler, "Signaturen als Bilder dekodieren zu wollen".

Wir empfehlen, die Bildbearbeitungsfunktion von Nano Banana 2 in mehrstufigen Dialogen über APIYI (apiyi.com) zu testen. Die Plattform übernimmt die Übertragung von thoughtSignature automatisch, bietet kostenlose Kontingente und eine einheitliche Schnittstelle.

📚 Referenzmaterialien

1. Offizielle Dokumentation zu Thought Signatures: Vollständige Erläuterung des thoughtSignature-Mechanismus von Google

   • Link: ai.google.dev/gemini-api/docs/thought-signatures
   • Beschreibung: Enthält Felddefinitionen, Übertragungsregeln und Beispiele für Dialoge mit mehreren Runden.

2. Dokumentation zum Gemini Thinking-Modus: Aktivierung und Konfigurationsparameter der Thinking-Funktion

   • Link: ai.google.dev/gemini-api/docs/thinking
   • Beschreibung: Erfahren Sie mehr über Konfigurationen wie include_thoughts und thinking_level.

3. Vertex AI Inference API-Referenz: Vollständige Felddefinitionen für Part-Objekte in der REST-API

   • Link: docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference
   • Beschreibung: Enthält Typdefinitionen und Nutzungseinschränkungen für thoughtSignature.

4. APIYI-Dokumentationszentrum: Vereinfachte Lösung für den Modellaufruf von Nano Banana 2 über die OpenAI-kompatible Schnittstelle

   • Link: docs.apiyi.com
   • Beschreibung: Automatische Verarbeitung der thoughtSignature-Übertragung zur Reduzierung der Entwicklungskomplexität.

Autor: APIYI Technik-Team
Technischer Austausch: Diskutieren Sie gerne in den Kommentaren. Weitere Informationen finden Sie im APIYI-Dokumentationszentrum unter docs.apiyi.com.