解讀 Nano Banana 2 API 的 thoughtSignature：爲什麼 base64 解碼後不是圖片？

作者注：深度解析 Nano Banana 2 API 響應中 thoughtSignature 字段的本質：它不是圖片而是加密的思考簽名，詳解 Thinking 模式響應結構、正確處理方式和常見踩坑

不少開發者在調用 Nano Banana 2 API 生成圖片時，發現響應裏除了圖片數據，還有一個 thoughtSignature 字段——它也是一長串 base64 編碼，看起來像圖片數據。嘗試解碼後發現根本轉不成圖片，這到底是什麼？本文將徹底講清楚 thoughtSignature 的本質、爲什麼它不是圖片、以及在多輪對話中如何正確處理它。

核心價值: 讀完本文，你將理解 thoughtSignature 的技術原理，避免把它誤當圖片處理，並掌握多輪對話中正確傳遞簽名的方法。

Nano Banana 2 API thoughtSignature 核心要點

先直接回答最常見的問題：thoughtSignature 不是圖片，不能解碼爲圖片，它是模型思考過程的加密簽名。

Nano Banana 2 API 響應中的 thoughtSignature 長什麼樣

當你調用 Nano Banana 2 生成圖片時，API 響應中的 parts 數組可能包含多個元素。典型的響應結構是這樣的：

{
  "candidates": [{
    "content": {
      "role": "model"，
      "parts": [
        {
          "text": "讓我思考一下如何生成這張圖片..."，
          "thought": true
        }，
        {
          "text": ""，
          "thoughtSignature": "CpcHAdHtim9+q4rstcbvQC0ic4x1/vqQlCJ..."
        }，
        {
          "inlineData": {
            "mime_type": "image/png"，
            "data": "iVBORw0KGgoAAAANSUhEUg..."
          }
        }
      ]
    }
  }]
}

這裏有三個 part，分別是：

1. 思考摘要（thought: true）：模型推理過程的文字概述
2. 思考簽名（thoughtSignature）：加密的推理狀態快照
3. 圖片數據（inlineData）：真正的圖片 base64 數據

關鍵問題就在於第 2 和第 3 個 part 都包含 base64 編碼數據，如果你的代碼沒有正確區分，就會把 thoughtSignature 誤當成圖片數據去解碼——然後發現怎麼都轉不成圖片。

Nano Banana 2 API thoughtSignature 的技術原理

理解了 thoughtSignature 不是圖片之後，再來看看它到底是什麼。

thoughtSignature 的本質

根據 Google 官方文檔的定義：

thoughtSignature（string，可選）："An opaque signature for the thought so it can be reused in subsequent requests. A base64-encoded string."

翻譯成大白話：thoughtSignature 是模型思考過程的"記憶快照"，經過加密簽名後以 base64 編碼形式返回。它的作用是讓模型在多輪對話中能夠"記住"之前的推理過程，從而保持思維連貫性。

幾個關鍵特徵：

• 不透明（Opaque）: 開發者無法解讀其內容，也無需關心內部結構
• 密碼學簽名: 由 Google 服務端簽名，無法僞造——傳一個隨機 base64 字符串會返回"無效簽名"錯誤
• 有狀態: 包含模型在生成當前回答時的推理鏈和中間計算結果

thoughtSignature 與 thought 的區別

這兩個字段經常搞混，但它們完全不同：

thought 是給人看的推理摘要，thoughtSignature 是給模型"看"的推理記憶。

Nano Banana 2 API 爲什麼需要 thoughtSignature

Nano Banana 2 屬於 Gemini 3.1 系列，支持 Thinking（思考）模式。模型在生成圖片前會先進行內部推理——分析提示詞意圖、規劃構圖、選擇色彩方案等。

這個推理過程的完整狀態被壓縮加密成 thoughtSignature。當你在多輪對話中進行圖片編輯（比如"把背景改成藍色"），模型需要恢復之前的推理狀態才能準確理解你的修改意圖。

如果不傳回 thoughtSignature：

• 純文本場景：不報錯，但推理質量和連貫性會下降
• 工具調用/函數調用場景：直接返回 HTTP 400 錯誤
• 圖片編輯多輪對話：可能丟失上下文，編輯結果不準確

🎯 開發建議: 在任何多輪對話場景中，都應該完整保留並回傳 thoughtSignature。
通過 API易 apiyi.com 調用時，平臺會自動處理簽名的傳遞和格式兼容，開發者無需手動管理。

Nano Banana 2 API thoughtSignature 正確處理方式

極簡示例：正確解析響應並區分圖片和簽名

以下代碼展示如何正確從 Nano Banana 2 的響應中提取圖片，同時保存 thoughtSignature 供後續使用：

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=["畫一隻在櫻花樹下的白貓"]，
    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"思考過程: {part.text[:100]}..."）
    elif hasattr（part， 'thought_signature'） and part.thought_signature:
        saved_signature = part.thought_signature  # 保存，不解碼！
        print（"已保存 thoughtSignature（非圖片）"）
    elif image := part.as_image（）:
        image.save（"cat_sakura.png"， format="PNG"）
        print（"圖片已保存"）

from google import genai
from google.genai import types

client = genai.Client（api_key="YOUR_API_KEY"）

# 第一輪：生成圖片
response1 = client.models.generate_content（
    model="gemini-3.1-flash-image-preview"，
    contents=["畫一隻在櫻花樹下的白貓"]，
    config=types.GenerateContentConfig（
        response_modalities=["TEXT"， "IMAGE"]，
        image_config=types.ImageConfig（image_size="2K"），
        thinking_config=types.ThinkingConfig（
            include_thoughts=True
        ），
    ）
）

# 提取圖片和簽名
image_data = None
thought_signature = None
model_parts = []

for part in response1.parts:
    model_parts.append（part）  # 保留完整的 parts
    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"）

# 第二輪：基於上一輪結果進行編輯
# 關鍵：將上一輪的完整 parts（含 thoughtSignature）作爲歷史傳入
history = [
    {"role": "user"， "parts": [{"text": "畫一隻在櫻花樹下的白貓"}]}，
    {"role": "model"， "parts": model_parts}，  # 包含 thoughtSignature
]

response2 = client.models.generate_content（
    model="gemini-3.1-flash-image-preview"，
    contents=history + [
        {"role": "user"， "parts": [{"text": "把背景改成夜空，加上月亮"}]}
    ]，
    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（"編輯後的圖片已保存"）

建議: 通過 API易 apiyi.com 調用 Nano Banana 2 時，平臺提供 OpenAI 兼容格式接口，自動處理 thoughtSignature 的傳遞，無需手動管理多輪對話的簽名狀態。

Nano Banana 2 API thoughtSignature 常見踩坑和解決方案

踩坑場景總結

Nano Banana 2 API thoughtSignature 字段命名對照

不同調用方式下字段命名不同，這是另一個常見坑點：

Nano Banana 2 API 應急方案：dummy 簽名

如果你在遷移舊對話歷史、沒有有效的 thoughtSignature，Google 提供了一個特殊的繞過值：

DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

將這個字符串作爲 thoughtSignature 的值傳入，可以避免 400 錯誤。但這只是應急方案，模型的推理連貫性會受影響。

🎯 最佳實踐: 從第一次調用開始就完整保存所有 thoughtSignature，建立正確的對話歷史鏈。
如果覺得手動管理太複雜，通過 API易 apiyi.com 使用 OpenAI 兼容接口可以大幅降低複雜度。

常見問題

總結

Nano Banana 2 API 中 thoughtSignature 的核心要點：

1. 不是圖片: thoughtSignature 是加密的思考過程簽名，不是 base64 圖片數據，不能解碼爲任何圖片格式
2. 必須原樣回傳: 在多輪對話中保存並原樣傳回 thoughtSignature，否則工具調用會 400 報錯，文本對話質量會下降
3. 正確區分三種 part: 有 inlineData 的是圖片，有 thoughtSignature 的是簽名，thought: true 的是思考摘要

理解這個字段的本質後，你在解析 Nano Banana 2 API 響應時就不會再踩"把簽名當圖片解碼"的坑了。

推薦通過 API易 apiyi.com 快速驗證 Nano Banana 2 的多輪對話圖片編輯功能，平臺自動處理 thoughtSignature 傳遞，提供免費額度和統一接口。

📚 參考資料

1. Thought Signatures 官方文檔: Google 對 thoughtSignature 機制的完整說明

   • 鏈接: ai.google.dev/gemini-api/docs/thought-signatures
   • 說明: 包含字段定義、傳遞規則和多輪對話示例

2. Gemini Thinking 模式文檔: Thinking 功能的開啓方式和配置參數

   • 鏈接: ai.google.dev/gemini-api/docs/thinking
   • 說明: 瞭解 include_thoughts、thinking_level 等配置

3. Vertex AI 推理 API 參考: REST API 中 Part 對象的完整字段定義

   • 鏈接: docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference
   • 說明: 包含 thoughtSignature 的類型定義和使用限制

4. API易文檔中心: 通過 OpenAI 兼容接口調用 Nano Banana 2 的簡化方案

   • 鏈接: docs.apiyi.com
   • 說明: 自動處理 thoughtSignature 傳遞，降低開發複雜度

作者: APIYI 技術團隊
技術交流: 歡迎在評論區討論，更多資料可訪問 API易 docs.apiyi.com 文檔中心