解決 Nano Banana 2 報錯 thought_signature 400 錯誤：多輪圖像編輯必須回傳思維簽名

作者注：Nano Banana 2 報錯 Image part is missing a thought_signature 怎麼辦？這是多輪對話時未回傳思維簽名導致的 400 錯誤。本文詳解原因、修復方案和代碼示例。

如果你在使用 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."
  }
}

不用慌——這是 Gemini 3 系列模型的一個 多輪對話機制要求，而非內容安全問題或平臺故障。簡單來說：你在第二輪請求中發送了之前生成的圖像，但沒有附帶該圖像的 thought_signature（思維簽名）。

核心價值: 讀完本文，你將理解 thought_signature 的工作原理，掌握 3 種修復方案，並學會在多輪圖像編輯場景中正確處理思維簽名。

<！– SVG_COVER: 文章封面圖 – 展示 thought_signature 錯誤原因和修復路徑 –>

---

Nano Banana 2 thought_signature 錯誤的核心解讀

這個報錯到底是什麼意思

先逐字拆解這條錯誤消息：

字段	含義	說明
status_code: 400	請求參數錯誤	不是服務端錯誤，是客戶端傳參問題
Image part	請求中包含的圖像數據	你在第 2 輪請求中發送了圖像
missing a thought_signature	缺少思維簽名	這張圖是上一輪模型生成的，需要附帶簽名
content position 2， part position 1	在對話歷史的第 2 條消息（模型回覆），第 1 個 part	精確定位了缺失簽名的位置

一句話總結: Gemini API 是無狀態的，模型通過 thought_signature（思維簽名）在多輪對話間保持推理上下文。當你發起第二輪圖像編輯請求時，必須將上一輪模型返回的 thought_signature 原樣回傳，否則就會收到 400 錯誤。

爲什麼 Gemini 3 系列強制要求 thought_signature

對比	Gemini 2.x 系列	Gemini 3 系列 （含 NB2）
思維簽名	部分場景可選	所有 part 類型強制要求
驗證嚴格度	寬鬆	嚴格（缺失即 400）
適用範圍	主要用於函數調用	文本、圖像、函數調用全部適用
自動處理	官方 SDK 自動處理	官方 SDK 自動處理

Gemini 3 系列模型（包括 Nano Banana 2 所基於的 gemini-3.1-flash）強制要求思維簽名，原因是：

1. 推理狀態恢復: 思維簽名是模型內部推理過程的加密表示，讓模型在下一輪對話中恢復之前的「思考狀態」
2. 圖像編輯連續性: 對於多輪圖像編輯，模型需要理解「這張圖是我上一步生成的」才能正確執行編輯指令
3. 安全和一致性: 簽名機制確保對話歷史未被篡改，提升多輪交互的可靠性

🎯 關鍵認知: 這個 400 錯誤與內容安全策略（IMAGE_SAFETY）完全無關，也不是 API易平臺的問題。這是 Gemini 3 系列模型的正常機制要求，需要在代碼層面正確處理。

---

Nano Banana 2 thought_signature 錯誤的 3 種修復方案

<！– SVG_DIAGRAM: 3種修復方案對比和代碼結構圖 –>

方案 1: 使用官方 SDK 的 chat 功能（推薦）

如果你使用 Google 的官方 SDK（Python / Node.js / Java），最簡單的方式是使用 chat 功能，SDK 會自動管理 thought_signature：

from google import genai

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

# 使用 chat 功能，SDK 自動處理 thought_signature
chat = client.chats.create（model="gemini-3.1-flash-image-preview"）

# 第 1 輪: 生成圖像
response1 = chat.send_message（"畫一隻橘貓坐在窗臺上"）

# 第 2 輪: 編輯圖像 （signature 自動回傳）
response2 = chat.send_message（"給貓戴一頂聖誕帽"）

方案 2: 手動提取並回傳 thought_signature

如果你使用自定義 HTTP 調用或通過 OpenAI 兼容接口調用，需要手動處理簽名。關鍵邏輯是：從上一輪響應中提取 thought_signature，在下一輪請求的對應 part 中原樣附帶。

import openai

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://vip.apiyi.com/v1"
）

# 第 1 輪: 生成圖像
response1 = client.chat.completions.create（
    model="gemini-3.1-flash-image-preview"，
    messages=[{"role": "user"， "content": "畫一隻橘貓"}]
）

# 關鍵: 保存完整的 model response
# 包括圖像數據和 thought_signature
model_reply = response1.choices[0].message

# 第 2 輪: 編輯圖像
# 將上一輪的完整 model response 作爲對話歷史傳入
response2 = client.chat.completions.create（
    model="gemini-3.1-flash-image-preview"，
    messages=[
        {"role": "user"， "content": "畫一隻橘貓"}，
        model_reply，  # 完整回傳，包含 thought_signature
        {"role": "user"， "content": "給貓戴一頂帽子"}
    ]
）

方案 3: 改用單輪請求

如果你的場景不需要多輪對話編輯，可以每次都發送獨立的單輪請求，徹底避開 thought_signature 問題：

# 單輪圖像編輯: 直接傳入原圖 + 編輯指令
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": "給這隻貓戴一頂聖誕帽"}
        ]
    }]
）

🎯 推薦: 新項目建議使用方案 1（官方 SDK chat 功能），已有項目可根據改動量選擇方案 2 或 3。通過 API易 apiyi.com 調用 Nano Banana 2 時，方案 2 和 3 均可正常使用。

---

Nano Banana 2 thought_signature 常見誤區

誤區	事實
這是內容安全問題	不是。400 錯誤是參數校驗失敗，與 IMAGE_SAFETY 無關
這是 API 平臺的問題	不是。這是 Gemini 3 系列模型的機制要求
可以自己構造簽名	不行。簽名是加密的，必須原樣回傳模型返回的值
只有函數調用才需要	Gemini 3 系列所有 part 類型都可能需要
設置 thinking: off 可以避免	不行。即使 thinking 級別設爲 minimal，簽名仍然會返回且必須回傳

Nano Banana 2 響應中 thought_signature 的位置

在 Nano Banana 2 的響應數據中，需要注意兩種特殊的 part：

臨時圖像 （thought: true）: 模型推理過程中產生的中間圖像，標記爲 thought: true。這些是臨時數據，不需要展示給用戶。

最終圖像 （含 thought_signature）: 最終生成的圖像會包含一個 thought_signature 字段。這就是你需要在下一輪請求中回傳的簽名。

{
  "candidates": [{
    "content": {
      "parts": [
        {
          "inlineData": {"mimeType": "image/png"， "data": "..."}，
          "thought_signature": "CkYKRAo..."
        }
      ]
    }
  }]
}

🎯 技術細節: thought_signature 是加密字符串，長度通常在 200-500 字符之間。不要嘗試解析、修改或自己構造——收到什麼就回傳什麼。通過 API易 apiyi.com 調用時，響應格式與谷歌原生 API 完全一致。

---

Nano Banana 2 thought_signature 錯誤的排查清單

<！– SVG_COMPARISON: 錯誤排查清單和決策樹 –>

快速排查 4 步:

1. 確認是否多輪請求: 如果你的 messages 數組裏包含了之前 model 角色的回覆（特別是圖像數據），那就是多輪請求
2. 檢查是否保存了完整響應: 上一輪模型返回的 response 中是否包含 thought_signature 字段？是否被完整保存？
3. 檢查簽名是否被修改: JSON 序列化/反序列化過程中，簽名字符串有沒有被截斷或轉義？
4. 檢查 part 位置對齊: 錯誤消息中的 content position X， part position Y 可以幫你精確定位哪個 part 缺少簽名

---

常見問題

Q1: 單輪圖像生成也會遇到這個錯誤嗎？

通常不會。thought_signature 錯誤幾乎只在多輪對話中出現——當你將之前模型返回的圖像放入對話歷史併發送新請求時纔會觸發。單輪的文生圖或圖生圖（直接傳入原始圖片）不涉及對話歷史，不需要處理簽名。

Q2: 通過 OpenAI 兼容接口調用時如何處理？

通過 API易 apiyi.com 的 OpenAI 兼容接口調用 Nano Banana 2 時，關鍵是保存上一輪 model 回覆的完整對象，在下一輪請求時作爲對話歷史傳入。不要只保存圖像數據而丟棄其他字段。如果你的框架（如 Dify、Cherry Studio）自動管理對話歷史，確認它是否完整保留了 thought_signature。

Q3: thought: true 的臨時圖像需要回傳嗎？

需要。Nano Banana 2 在推理過程中可能返回標記爲 thought: true 的臨時圖像，這些是模型「思考過程」的一部分。在構建對話歷史時，所有 model 返回的 part（包括臨時圖像）都應該完整回傳。最安全的做法是直接回傳完整的 model response 對象。

---

總結

Nano Banana 2 thought_signature 400 錯誤的核心要點：

1. 不是內容安全問題: 這是 Gemini 3 系列模型的多輪對話機制要求，與 IMAGE_SAFETY 無關
2. 原因明確: 多輪請求時，未將上一輪模型返回的 thought_signature 原樣回傳
3. 修復方案: 使用官方 SDK chat 功能（自動處理）、手動提取回傳簽名、或改用單輪請求

記住核心原則：模型返回的 thought_signature 不要修改、不要丟棄、不要自己構造——收到什麼就回傳什麼。

如需通過第三方平臺調用 Nano Banana 2，推薦使用 API易 apiyi.com，響應格式與谷歌原生 API 完全一致，$0.05/次，不限併發。

---

📚 參考資料

1. Google 官方 Thought Signatures 文檔: 思維簽名機制詳解

   • 鏈接: ai.google.dev/gemini-api/docs/thought-signatures
   • 說明: 官方文檔，包含工作原理、model 行爲和 SDK 處理方式

2. Google Gemini 3 開發者指南: Gemini 3 系列新特性

   • 鏈接: ai.google.dev/gemini-api/docs/gemini-3
   • 說明: Gemini 3 系列的簽名強制要求和新功能說明

3. Google 圖像生成文檔: Nano Banana 圖像生成最佳實踐

   • 鏈接: ai.google.dev/gemini-api/docs/image-generation
   • 說明: 多輪圖像編輯中的 thought_signature 使用建議

4. Google Cloud Vertex AI 文檔: 企業級思維簽名說明

   • 鏈接: docs.google.com/vertex-ai/generative-ai/docs/thought-signatures
   • 說明: Vertex AI 環境下的簽名處理和配置方法

---

作者: APIYI 技術團隊
技術交流: 歡迎在評論區討論 Nano Banana 2 多輪編輯的實現心得，更多資料可訪問 API易 docs.apiyi.com 文檔中心