Интерпретация thoughtSignature в API Nano Banana 2: почему после декодирования base64 получается не изображение?

title: "Разбор Nano Banana 2 API: что такое thoughtSignature и как с ним работать"
description: "Разбираемся, почему thoughtSignature в API Nano Banana 2 — это не картинка, а важный элемент логики модели, и как правильно использовать его в многошаговых диалогах."

Авторская заметка: Глубокий разбор сути поля thoughtSignature в ответе API Nano Banana 2: это не изображение, а зашифрованная подпись процесса мышления. Подробно разбираем структуру ответа в режиме Thinking, правильные способы обработки и типичные ошибки.

Многие разработчики при вызове API Nano Banana 2 для генерации изображений замечают, что помимо самих данных изображения в ответе присутствует поле thoughtSignature. Оно также представляет собой длинную строку в формате base64 и внешне напоминает данные картинки. Попытки декодировать его приводят к ошибкам, так как это вовсе не изображение. Что же это такое? В этой статье мы подробно разберем суть thoughtSignature, объясним, почему это не картинка и как правильно обрабатывать это поле в многошаговых диалогах.

Основная ценность: Прочитав эту статью, вы поймете технические принципы работы thoughtSignature, перестанете путать его с данными изображения и научитесь корректно передавать подпись в последующих запросах.

Основные моменты API Nano Banana 2: thoughtSignature

Давайте сразу ответим на самый частый вопрос: thoughtSignature — это не изображение, его нельзя декодировать как картинку. Это зашифрованная подпись процесса «мышления» модели.

Как выглядит thoughtSignature в ответе API Nano Banana 2

Когда вы вызываете Nano Banana 2 для генерации изображения, массив parts в ответе API может содержать несколько элементов. Типичная структура ответа выглядит так:

{
  "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-данные самого изображения.

Главная проблема в том, что и вторая, и третья части содержат данные в формате base64. Если ваш код не различает их правильно, он может ошибочно принять thoughtSignature за данные изображения и попытаться их декодировать — и, разумеется, ничего не получится.

Технические принципы thoughtSignature в API Nano Banana 2

Разобравшись с тем, что thoughtSignature — это вовсе не изображение, давайте детально рассмотрим, что же это такое на самом деле.

Суть thoughtSignature

Согласно официальной документации Google:

thoughtSignature (строка, необязательно): «Непрозрачная подпись для процесса мышления, позволяющая повторно использовать его в последующих запросах. Строка в кодировке base64».

Простыми словами: thoughtSignature — это «снимок памяти» процесса мышления модели, который возвращается в виде зашифрованной подписи в формате base64. Его задача — позволить модели «запоминать» ход своих рассуждений в многоходовых диалогах, обеспечивая логическую связность.

Ключевые характеристики:

• Непрозрачность (Opaque): разработчик не может прочитать содержимое и не должен вникать во внутреннюю структуру.
• Криптографическая подпись: подписывается на стороне сервера Google, подделать её невозможно — при передаче случайной строки base64 вы получите ошибку «недействительная подпись».
• Состояние (Stateful): содержит цепочку рассуждений и промежуточные вычисления, которые модель выполнила при генерации текущего ответа.

Разница между thoughtSignature и thought

Эти поля часто путают, но они выполняют совершенно разные функции:

thought — это краткое изложение рассуждений для человека, а thoughtSignature — это «воспоминания» о рассуждениях для самой модели.

Зачем API Nano Banana 2 нужен thoughtSignature

Nano Banana 2 относится к серии Gemini 3.1 и поддерживает режим Thinking (мышление). Перед генерацией изображения модель проводит внутренний анализ: оценивает намерение промпта, планирует композицию, подбирает цветовую схему и т.д.

Полное состояние этого процесса сжимается и шифруется в thoughtSignature. Когда вы редактируете изображение в ходе диалога (например, просите «смени фон на синий»), модели необходимо восстановить предыдущее состояние рассуждений, чтобы точно понять, что именно нужно изменить.

Если не передавать thoughtSignature обратно:

• В чисто текстовых сценариях: ошибки не будет, но качество рассуждений и связность упадут.
• В сценариях вызова инструментов/функций: вернется ошибка HTTP 400.
• В многоходовых диалогах по редактированию изображений: контекст может потеряться, и результат редактирования будет неточным.

🎯 Совет для разработчиков: в любых сценариях многоходового диалога всегда сохраняйте и передавайте thoughtSignature обратно. При использовании APIYI (apiyi.com) платформа автоматически берет на себя передачу подписей и совместимость форматов, поэтому вам не нужно управлять этим вручную.

Как правильно работать с thoughtSignature в API Nano Banana 2

Минималистичный пример: корректный разбор ответа и разделение изображения и подписи

Следующий код показывает, как правильно извлечь изображение из ответа 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)  # Сохраняем полные части ответа
    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")

# Второй шаг: редактирование на основе предыдущего результата
# Ключевой момент: передаем полные части (включая 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("Отредактированное изображение сохранено")

Совет: при вызове Nano Banana 2 через APIYI (apiyi.com) платформа предоставляет интерфейс, совместимый с OpenAI, и автоматически обрабатывает передачу thoughtSignature, избавляя вас от необходимости вручную управлять состоянием подписи в диалогах.

Распространенные ошибки и решения при работе с thoughtSignature в API Nano Banana 2

Сводная таблица типичных проблем

Соответствие имен полей thoughtSignature в API Nano Banana 2

Именование полей зависит от способа вызова, что часто сбивает с толку:

Аварийное решение для API Nano Banana 2: фиктивная (dummy) подпись

Если вы переносите старую историю диалогов и у вас нет валидной thoughtSignature, Google предоставляет специальное значение для обхода:

DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

Передача этой строки в качестве значения thoughtSignature поможет избежать ошибки 400. Однако это лишь временная мера, которая может негативно повлиять на логическую связность ответов модели.

🎯 Лучшая практика: Сохраняйте все thoughtSignature с самого первого вызова, чтобы выстроить корректную цепочку истории диалога.
Если ручное управление кажется слишком сложным, использование OpenAI-совместимого интерфейса через APIYI (apiyi.com) поможет значительно упростить процесс.

Часто задаваемые вопросы

Резюме

Ключевые моменты о thoughtSignature в API Nano Banana 2:

1. Это не изображение: thoughtSignature — это зашифрованная подпись процесса рассуждений, а не base64-данные изображения; её невозможно декодировать в какой-либо графический формат.
2. Необходимо передавать обратно в исходном виде: Сохраняйте и возвращайте thoughtSignature в многоходовых диалогах, иначе вызов инструментов приведет к ошибке 400, а качество текстового диалога упадет.
3. Правильно различайте три типа частей (part): с inlineData — изображения, с thoughtSignature — подписи, с thought: true — краткое изложение мыслей.

Поняв суть этого поля, вы больше не попадете в ловушку «декодирования подписи как изображения» при работе с ответами API Nano Banana 2.

Рекомендуем использовать APIYI (apiyi.com) для быстрой проверки функций редактирования изображений в многоходовых диалогах Nano Banana 2: платформа автоматически обрабатывает передачу thoughtSignature, предоставляет бесплатные лимиты и унифицированный интерфейс.

📚 Справочные материалы

1. Официальная документация Thought Signatures: Полное описание механизма thoughtSignature от Google.

   • Ссылка: ai.google.dev/gemini-api/docs/thought-signatures
   • Описание: содержит определения полей, правила передачи данных и примеры многоходовых диалогов.

2. Документация режима Gemini Thinking: Способы активации и параметры конфигурации функции Thinking.

   • Ссылка: ai.google.dev/gemini-api/docs/thinking
   • Описание: разбор конфигураций include_thoughts, thinking_level и других.

3. Справочник API логических выводов Vertex AI: Полное определение полей объекта Part в REST API.

   • Ссылка: docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference
   • Описание: включает определения типов и ограничения использования thoughtSignature.

4. Центр документации APIYI: Упрощенная схема вызова Nano Banana 2 через совместимый с OpenAI интерфейс.

   • Ссылка: docs.apiyi.com
   • Описание: автоматическая обработка передачи thoughtSignature для снижения сложности разработки.

Автор: Техническая команда APIYI
Техническое обсуждение: Приглашаем к дискуссии в комментариях. Больше материалов можно найти в центре документации APIYI по адресу docs.apiyi.com.