Nano Banana 2 APIのthoughtSignatureの解読：なぜbase64デコードしても画像にならないのか？

description: Nano Banana 2 APIの「thoughtSignature」フィールドの正体を徹底解説。画像データと誤解されがちなこのフィールドの技術的本質、正しい扱い方、多輪対話での活用法を分かりやすく紹介します。

作者注：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..."
          }
        }
      ]
    }
  }]
}

ここには 3 つの part があります：

1. 思考の要約（thought: true）：モデルの推論プロセスのテキスト概要
2. 思考署名（thoughtSignature）：暗号化された推論状態のスナップショット
3. 画像データ（inlineData）：実際の画像 base64 データ

重要なのは、第 2 と第 3 の part がどちらも base64 エンコードデータを含んでいる点です。コード内で正しく区別できていないと、thoughtSignature を誤って画像データとしてデコードしようとしてしまい、「画像に変換できない」という問題が発生します。

title: Nano Banana 2 API thoughtSignature の技術的原理
description: Nano Banana 2 APIにおけるthoughtSignatureの正体と、その役割、そして多輪対話での正しい処理方法について解説します。

Nano Banana 2 API thoughtSignature の技術的原理

thoughtSignature が画像ではないことを理解したところで、それが一体何なのかを詳しく見ていきましょう。

thoughtSignature の本質

Google の公式ドキュメントによる定義は以下の通りです：

thoughtSignature（string、オプション）: "後続のリクエストで再利用できるようにするための、思考の不透明な署名。Base64エンコードされた文字列。"

平たく言えば、thoughtSignature はモデルの思考プロセスの「記憶スナップショット」であり、暗号化された署名を経て Base64 エンコード形式で返されるものです。その役割は、モデルが多輪対話の中で以前の推論プロセスを「記憶」し、思考の整合性を維持できるようにすることです。

主な特徴は以下の通りです：

• 不透明（Opaque）: 開発者はその内容を解読できず、内部構造を気にする必要もありません。
• 暗号学的署名: Google のサーバー側で署名されており、偽造は不可能です。ランダムな Base64 文字列を渡すと「無効な署名」エラーが返されます。
• ステートフル（状態保持）: モデルが現在の回答を生成する際の推論チェーンと中間計算結果が含まれています。

thoughtSignature と thought の違い

この2つのフィールドは混同されがちですが、全くの別物です：

thought は人間が見るための推論要約であり、thoughtSignature はモデルが「見る」ための推論記憶です。

Nano Banana 2 API で thoughtSignature が必要な理由

Nano Banana 2 は Gemini 3.1 シリーズに属しており、Thinking（思考）モードをサポートしています。モデルは画像を生成する前に、プロンプトの意図分析、構図の計画、配色案の選択といった内部推論を行います。

この推論プロセスの完全な状態が圧縮・暗号化され、thoughtSignature となります。多輪対話の中で画像編集（例：「背景を青にして」）を行う際、モデルは以前の推論状態を復元しなければ、あなたの修正意図を正確に理解できません。

thoughtSignature を返送しない場合：

• テキストのみのシナリオ：エラーにはなりませんが、推論の品質や整合性が低下します。
• ツール呼び出し/関数呼び出しのシナリオ：HTTP 400 エラーが直接返されます。
• 画像編集の多輪対話：コンテキストが失われ、編集結果が不正確になる可能性があります。

🎯 開発アドバイス: 多輪対話のあらゆるシナリオにおいて、thoughtSignature を完全な形で保持し、返送するようにしてください。
APIYI (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")

# 第1ラウンド：画像を生成
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")

# 第2ラウンド：前回の結果に基づいて編集
# 重要：前回の完全な 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("編集後の画像を保存しました")

アドバイス: APIYI (apiyi.com) を通じて Nano Banana 2 を呼び出す場合、プラットフォームが OpenAI 互換フォーマットのインターフェースを提供しており、thoughtSignature の受け渡しを自動的に処理するため、多輪対話の署名状態を手動で管理する必要はありません。

Nano Banana 2 API の thoughtSignature に関するよくある落とし穴と解決策

落とし穴のまとめ

Nano Banana 2 API の thoughtSignature フィールド命名対照表

呼び出し方法によってフィールド名が異なります。これもよくある落とし穴です：

Nano Banana 2 API の緊急対応策：ダミー署名

古い対話履歴を移行する際などで有効な thoughtSignature がない場合、Google は特別なバイパス値を提供しています：

# 緊急時の回避策として使用
DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

この文字列を thoughtSignature の値として渡すことで、400 エラーを回避できます。ただし、これはあくまで緊急手段であり、モデルの推論の一貫性に影響が出る可能性がある点に注意してください。

🎯 ベストプラクティス: 初回の呼び出しからすべての thoughtSignature を完全に保存し、正しい対話履歴チェーンを構築してください。
手動での管理が複雑だと感じる場合は、APIYI (apiiyi.com) を通じて OpenAI 互換インターフェースを利用することで、複雑さを大幅に軽減できます。

よくある質問

まとめ

Nano Banana 2 API における thoughtSignature の核心ポイント：

1. 画像ではない: thoughtSignature は暗号化された思考プロセスの署名であり、base64 画像データではありません。いかなる画像形式にもデコードできません。
2. そのまま送り返す必要がある: マルチターン対話では thoughtSignature を保存し、そのまま送り返してください。そうしないとツール呼び出しで 400 エラーが発生し、テキスト対話の品質も低下します。
3. 3種類の part を正しく区別する: inlineData があるものは画像、thoughtSignature があるものは署名、thought: true があるものは思考の要約です。

このフィールドの本質を理解すれば、Nano Banana 2 API のレスポンスを解析する際に「署名を画像としてデコードしようとする」といったミスを防ぐことができます。

APIYI (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. APIYI ドキュメントセンター: OpenAI 互換インターフェースを通じて Nano Banana 2 を呼び出すための簡略化ソリューション

   • リンク: docs.apiyi.com
   • 説明: thoughtSignature の受け渡しを自動化し、開発の複雑さを軽減します。

著者: APIYI 技術チーム
技術交流: コメント欄での議論を歓迎します。その他の資料については、APIYI ドキュメントセンター（docs.apiyi.com）をご覧ください。