作者注：深度解析 Nano Banana Pro （gemini-3-pro-image-preview） 多輪對話出圖 API 的字段結構、contents 數組構造、thoughtSignature 機制與代碼實戰。
 

很多開發者第一次接入 Nano Banana Pro 都會遇到同一個困惑：在 gemini.google.com 網頁端可以連續追問「把背景換成黃昏」「再加一隻貓」，模型完美記得上一張圖；但調用官方 API 時，模型卻像斷片一樣什麼都不記得。原因是 Gemini API 本身是無狀態的，多輪上下文必須由調用方手動構造。本文將徹底講清 Nano Banana Pro 多輪對話出圖 API 的底層字段、Python SDK 與 REST 兩套實現，以及關鍵的 thoughtSignature 機制，幫你 3 步搭建出像網頁版一樣流暢的上下文出圖體驗。

核心價值: 讀完本文，你將掌握 contents 數組的正確構造方式、能在自己的應用裏實現「基於上一張圖繼續編輯」的多輪工作流，並避免「圖片忘記」「token 浪費」「signature 丟失」三大典型坑。

gemini.google.com 是 Google 官方搭建的 Agent 應用，它在前端幫你維護了一份完整的「對話狀態」（包含每輪的文本、生成的圖片、思考簽名），每次你輸入新消息時，這個 Agent 會把所有歷史一次性打包發送給底層模型。這就是爲什麼網頁端體驗如此流暢——所有「記憶」工作都被 Agent 包攬了。

而當你直接調用 generateContent API 時，你拿到的是「赤裸」的模型調用接口。每次 HTTP 請求都是一次獨立的推理，模型對你之前的對話毫無概念。要復現網頁版的多輪體驗，本質上就是在你的代碼裏自己實現一個 Agent——把歷史 user 消息、model 響應（含圖片和簽名）按規範填入 contents，再發起請求。

contents 是 Gemini API 表達對話歷史的標準字段，它是一個 JSON 數組，每個元素代表一輪發言：

一個完整的兩輪對話請求體長這樣：

{ "contents": [ {"role": "user"， "parts": [{"text": "生成一隻在沙灘奔跑的金毛犬"}]}， {"role": "model"， "parts": [ {"inline_data": {"mime_type": "image/png"， "data": " 
    
    
      <第一輪生成圖base64>
        "}}， {"thought_signature": " 
       <加密簽名>
         "} ]}， {"role": "user"， "parts": [{"text": "把場景改成黃昏時分"}]} ]， "generationConfig": { "responseModalities": ["TEXT"， "IMAGE"]， "imageConfig": {"aspectRatio": "16:9"， "imageSize": "2K"} } } 
        
      

第二輪請求裏，模型必須能「看到」第一輪生成的圖片。Nano Banana Pro 支持兩種回傳姿勢：

# 方式一：inline_data 內嵌 base64（適合小圖，簡單直接） { "inline_data": { "mime_type": "image/png"， "data": base64.b64encode（image_bytes）.decode（） } } # 方式二：file_data 引用 Files API 上傳後的資源（適合大圖或複用） { "file_data": { "mime_type": "image/png"， "file_uri": "files/abc123xyz" } } 

關鍵提示: inline_data 是直接調用最常用的方式，適合一次性場景；file_data 引用模式適合需要在多輪中複用同一張大圖的場景，可顯著降低請求體大小和上傳開銷。

如果你使用官方 Python SDK，最簡潔的寫法只需要 10 行：

from google import genai client = genai.Client（api_key="YOUR_API_KEY"） chat = client.chats.create（model="gemini-3-pro-image-preview"） # 第一輪：生成初始圖 r1 = chat.send_message（"生成一隻在沙灘奔跑的金毛犬"） # 第二輪：基於第一張圖繼續編輯（chat 對象自動攜帶歷史） r2 = chat.send_message（"把場景改成黃昏時分，加一隻飛翔的海鷗"） # 第三輪：繼續追加修改 r3 = chat.send_message（"再把狗的顏色換成深棕色"） 

chat 對象內部維護了完整的 contents 列表（包括每輪的 thoughtSignature），開發者無需關心字段細節。每次 send_message 都會自動把歷史打包發送。

import openai import base64 client = openai.OpenAI（ api_key="YOUR_API_KEY"， base_url="https://vip.apiyi.com/v1" ） # 維護一個本地的 messages 列表（即 contents 概念） messages = [ {"role": "user"， "content": "生成一隻在沙灘奔跑的金毛犬"} ] # 第一輪 response1 = client.chat.completions.create（ model="gemini-3-pro-image-preview"， messages=messages ） img1_url = response1.choices[0].message.content # 提取圖片URL或base64 # 把模型響應加入歷史 messages.append（{"role": "assistant"， "content": img1_url}） # 第二輪：追加新指令 messages.append（{"role": "user"， "content": "把場景改成黃昏時分"}） response2 = client.chat.completions.create（ model="gemini-3-pro-image-preview"， messages=messages ） # 第三輪繼續追加... messages.append（{"role": "assistant"， "content": response2.choices[0].message.content}） messages.append（{"role": "user"， "content": "再加一隻飛翔的海鷗"}） response3 = client.chat.completions.create（ model="gemini-3-pro-image-preview"， messages=messages ） 

建議: 對於多輪編輯場景，推薦使用 SDK 的 chat 對象或維護本地 messages 列表，避免每次手動拼接 contents。可在 API易 apiyi.com 註冊免費額度，先用 SDK 跑通再考慮 REST 優化。

某些場景（例如服務端中轉、ComfyUI 節點、低代碼平臺）無法使用官方 SDK，需要直接構造 REST 請求。以下是完整的 curl 調用：

# 第一輪：純文本指令生成圖 curl -X POST "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" -H "x-goog-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ "contents": [ {"role": "user"， "parts": [{"text": "生成一隻在沙灘奔跑的金毛犬"}]} ]， "generationConfig": { "responseModalities": ["TEXT"， "IMAGE"] } }' # 響應中會有: parts[0].inline_data.data （base64圖片） # 以及 parts[0].thought_signature 

第二輪請求時，必須把第一輪的整個 model 響應（包括圖片和簽名）原樣塞回 contents：

curl -X POST "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" -H "x-goog-api-key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ "contents": [ {"role": "user"， "parts": [{"text": "生成一隻在沙灘奔跑的金毛犬"}]}， {"role": "model"， "parts": [ {"inline_data": {"mime_type": "image/png"， "data": " 
      
    
        <第一輪返回的base64>
          "}}， {"thought_signature": " 
         <第一輪返回的signature>
           "} ]}， {"role": "user"， "parts": [{"text": "把場景改成黃昏時分"}]} ]， "generationConfig": { "responseModalities": ["TEXT"， "IMAGE"] } }' 
          
        

數據說明: 上圖展示了 Agent 自動管理 vs API 手動管理的核心差異，可通過 API易 apiyi.com 平臺直接對比兩種調用方式的實際表現差異。

thoughtSignature 是 Gemini 3 系列引入的「加密思考簽名」。它是模型對自己內部推理狀態的一個緊湊編碼，肉眼不可讀，但模型在下一輪可以用它快速恢復上下文。具體作用：

• 保留細節決策: 例如第一輪裏模型「決定」用淺色調，第二輪通過簽名繼承這個風格
• 提升一致性: 角色、場景、構圖在多輪編輯中保持穩定
• 節省 token: 避免在 prompt 裏反覆重申「保持原風格」

import requests import base64 import json API_BASE = "https://vip.apiyi.com/v1beta" MODEL = "gemini-3-pro-image-preview" HEADERS = { "x-goog-api-key": "YOUR_API_KEY"， "Content-Type": "application/json" } class NanoBananaChat: """手動維護 contents + signature 的極簡 chat 客戶端""" def __init__（self）: self.contents = [] def send（self， text: str， attach_image_b64: str = None） -> dict: # 構造本輪 user message user_parts = [{"text": text}] if attach_image_b64: user_parts.append（{ "inline_data": {"mime_type": "image/png"， "data": attach_image_b64} }） self.contents.append（{"role": "user"， "parts": user_parts}） # 發起請求 resp = requests.post（ f"{API_BASE}/models/{MODEL}:generateContent"， headers=HEADERS， json={ "contents": self.contents， "generationConfig": {"responseModalities": ["TEXT"， "IMAGE"]} } ）.json（） # 把 model 響應（含 signature）原樣追加回 contents model_parts = resp["candidates"][0]["content"]["parts"] self.contents.append（{"role": "model"， "parts": model_parts}） return model_parts # 使用示例 chat = NanoBananaChat（） parts1 = chat.send（"生成一隻在沙灘奔跑的金毛犬"） parts2 = chat.send（"把場景改成黃昏時分"） # 自動攜帶歷史和signature parts3 = chat.send（"再加一隻飛翔的海鷗"） 

優化建議: 通過 API易 apiyi.com 接入時，平臺層會原樣透傳 thought_signature 字段，開發者只需保證「把整個 model parts 數組追加回 contents」即可，無需關心簽名的具體內容。

營銷團隊常見需求：基於一張產品概念圖，逐步調整文案、配色、排版。多輪對話出圖 API 的優勢在於每次只需描述「增量變化」，不必從頭描述整張圖：

chat = client.chats.create（model="gemini-3-pro-image-preview"） chat.send_message（"設計一張深藍漸變背景的咖啡品牌海報，左側放產品圖"） chat.send_message（"把標題文案改成「Awaken Your Morning」"） chat.send_message（"右下角加一個二維碼佔位"） chat.send_message（"整體風格再現代一點，去掉裝飾花邊"） 

Nano Banana Pro 支持單次最多 14 張參考圖。結合多輪對話，可以構建強大的圖像融合工作流：

# 上傳一張人像 + 一張服裝參考圖 chat.send_message（[

"把第一張圖的人物穿上第二張圖裏的服裝"， {"inline_data": {"mime_type": "image/png"， "data": person_b64}}， {"inline_data": {"mime_type": "image/png"， "data": outfit_b64}} 

]）

後續微調

chat.send_message（"把領口改成 V 字領"） chat.send_message（"背景換成簡潔的灰色"）

如果用戶在前端關閉頁面後重新打開，希望繼續上次對話，需要把 contents 數組持久化到數據庫：

import json

保存

with open（f"sessions/{user_id}.json"， "w"） as f:

json.dump（chat.get_history（）， f） 

恢復

with open（f"sessions/{user_id}.json"） as f:

history = json.load（f） 

restored_chat = client.chats.create（

model="gemini-3-pro-image-preview"， history=history 

） restored_chat.send_message（"繼續上次的，把背景再亮一點"）

場景建議: 當對話超過 8-10 輪時，建議主動「截斷」前面的歷史或用 LLM 摘要替代，否則 token 會快速逼近 64K 上限。生產環境務必加入 token 計數器，提前在客戶端做截斷決策。

Nano Banana Pro 多輪對話出圖 API 的核心要點：

1. 無狀態本質: API 不記憶任何歷史，必須由調用方維護 contents 數組
2. 角色交替: user 與 model 嚴格交替，每輪 parts 可混合 text/image/signature
3. 圖片回傳: 上一輪生成的圖必須以 inline_data 形式塞回，否則模型「看不到」
4. 簽名機制: thought_signature 是多輪一致性的關鍵，REST 模式下必須手動攜帶
5. SDK 簡化: 官方 Python SDK 的 chat 對象可自動管理上述所有細節

對於希望快速實現網頁版體驗的開發者，**路徑是使用官方 SDK 的 chat 對象或 OpenAI 兼容接口的 messages 模式，避免手動構造 REST 帶來的複雜度。

推薦通過 API易 apiyi.com 接入 Nano Banana Pro 多輪對話出圖能力，平臺支持原生 Gemini 字段與 OpenAI 兼容雙模式調用，提供免費測試額度，便於快速驗證多輪編輯效果並平滑遷移現有項目。

1. Gemini API 圖像生成官方文檔: 多輪對話出圖的權威說明
   • 鏈接: ai.google.dev/gemini-api/docs/image-generation
   • 說明: 包含 contents 字段規範、Python SDK 與 REST 完整示例
2. Gemini 3 Pro Image Preview 模型卡: 模型能力與限制說明
   • 鏈接: ai.google.dev/gemini-api/docs/models/gemini-3-pro-image-preview
   • 說明: 上下文窗口、分辨率、參考圖數量等關鍵參數
3. Google AI Developers Forum – Multi-turn Nano Banana: 社區實戰示例
   • 鏈接: discuss.ai.google.dev/t/multi-turn-nano-banana-example
   • 說明: 真實開發者討論的多輪對話**實踐
4. Vertex AI Gemini 3 Pro Image 文檔: 企業級部署參考
   • 鏈接: docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image
   • 說明: 包含 thought_signature 與 file_data 引用的高級用法
5. API易 Nano Banana Pro 接入文檔: 國內開發者快速上手
   • 鏈接: help.apiyi.com
   • 說明: 包含 OpenAI 兼容接口、原生 Gemini 接口雙模式示例

作者: APIYI 技術團隊
技術交流: 歡迎在評論區分享你在多輪對話出圖中遇到的實戰問題，更多 Nano Banana Pro 配置技巧可訪問 API易 docs.apiyi.com 文檔中心