Авторская заметка: Столкнулись с ошибкой «Image part is missing a thought_signature» в Nano Banana 2? Это ошибка 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 способа исправления и научитесь правильно обрабатывать сигнатуры мышления в сценариях многоходового редактирования изображений.
Разбор ошибки thought_signature в Nano Banana 2
Что на самом деле означает эта ошибка
Давайте разберем сообщение об ошибке по частям:
| Поле | Значение | Пояснение |
|---|---|---|
| status_code: 400 | Ошибка параметров запроса | Это не ошибка сервера, а проблема с передачей данных клиентом |
| Image part | Данные изображения в запросе | Вы отправили изображение во 2-м раунде запроса |
| missing a thought_signature | Отсутствует «подпись мышления» | Это изображение было создано моделью ранее, нужна подпись |
| content position 2, part position 1 | 2-е сообщение в истории, 1-я часть | Точное указание места, где не хватает подписи |
Краткий итог: API Gemini не имеет состояния (stateless), и модель использует thought_signature (подпись мышления) для сохранения контекста рассуждений между раундами диалога. Когда вы отправляете второй запрос на редактирование изображения, вы обязаны вернуть thought_signature, полученную от модели в предыдущем ответе, иначе получите ошибку 400.
Почему серия Gemini 3 требует thought_signature
| Сравнение | Серия Gemini 2.x | Серия Gemini 3 (вкл. NB2) |
|---|---|---|
| Подпись мышления | Опционально в ряде сценариев | Обязательна для всех типов part |
| Строгость проверки | Мягкая | Строгая (отсутствие = 400) |
| Область применения | В основном вызов функций | Текст, изображения, вызов функций |
| Автоматизация | Официальный SDK | Официальный SDK |
Модели серии Gemini 3 (включая gemini-3.1-flash, на базе которой работает Nano Banana 2) требуют подпись мышления по следующим причинам:
- Восстановление состояния рассуждений: Подпись — это зашифрованное представление внутреннего процесса мышления модели, позволяющее ей «вспомнить» ход своих мыслей в следующем раунде.
- Непрерывность редактирования: Для многошагового редактирования модели нужно понимать: «это изображение создала я на предыдущем шаге», чтобы корректно выполнить правки.
- Безопасность и согласованность: Механизм подписи гарантирует, что история диалога не была подделана, что повышает надежность многоходового взаимодействия.
🎯 Важный вывод: Эта ошибка 400 никак не связана с политиками безопасности контента (IMAGE_SAFETY) и не является проблемой платформы APIYI. Это стандартный механизм работы моделей серии Gemini 3, который нужно учитывать при написании кода.
3 способа исправления ошибки thought_signature в Nano Banana 2
Способ 1: Использование функции chat в официальном SDK (рекомендуется)
Если вы используете официальный SDK от Google (Python / Node.js / Java), проще всего использовать функцию chat — SDK автоматически управляет thought_signature:
from google import genai
client = genai.Client(api_key="ВАШ_API_КЛЮЧ")
# Используем функцию 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="ВАШ_API_КЛЮЧ",
base_url="https://vip.apiyi.com/v1"
)
# 1-й раунд: генерация изображения
response1 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[{"role": "user", "content": "Нарисуй рыжего кота"}]
)
# Ключевой момент: сохраняем полный ответ модели
# Включая данные изображения и thought_signature
model_reply = response1.choices[0].message
# 2-й раунд: редактирование
# Передаем полный ответ модели как часть истории диалога
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 (функция chat в официальном SDK). Для существующих проектов выбирайте Способ 2 или 3 в зависимости от объема изменений. При вызове Nano Banana 2 через APIYI (apiyi.com) способы 2 и 3 будут работать корректно.
Распространенные заблуждения о thought_signature в Nano Banana 2
| Заблуждение | Факты |
|---|---|
| Это проблема безопасности контента | Нет. Ошибка 400 означает сбой проверки параметров, это не связано с IMAGE_SAFETY |
| Это проблема платформы API | Нет. Это требование механизма моделей серии Gemini 3 |
| Можно сгенерировать подпись самостоятельно | Нельзя. Подпись зашифрована, необходимо возвращать значение, полученное от модели, в исходном виде |
| Нужно только для вызова функций | Может потребоваться для всех типов part в серии Gemini 3 |
Можно избежать, установив thinking: off |
Нельзя. Даже если уровень мышления установлен на minimal, подпись все равно будет возвращена и её необходимо вернуть |
Расположение thought_signature в ответе Nano Banana 2
В данных ответа 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 (apiyi.com) формат ответа полностью совпадает с оригинальным API Google.
Чек-лист для устранения ошибок thought_signature в Nano Banana 2
4 шага для быстрой диагностики:
- Проверьте, является ли запрос многоходовым: если ваш массив
messagesсодержит предыдущие ответы ролиmodel(особенно данные изображений), значит, это многоходовый запрос. - Проверьте, сохранен ли полный ответ: содержит ли
responseот предыдущего шага полеthought_signature? Было ли оно сохранено полностью? - Проверьте, не была ли изменена подпись: не была ли строка подписи усечена или экранирована в процессе сериализации/десериализации JSON?
- Проверьте выравнивание позиций part: сообщение об ошибке с указанием
content position X, part position Yпоможет вам точно определить, в каком именно part отсутствует подпись.
Часто задаваемые вопросы
Q1: Возникает ли эта ошибка при генерации изображений за один проход?
Обычно нет. Ошибка thought_signature встречается почти исключительно в многоходовых диалогах — она срабатывает, когда вы включаете изображение, полученное от модели ранее, в историю диалога и отправляете новый запрос. Одноходовая генерация «текст-в-изображение» или «изображение-в-изображение» (с прямой передачей исходного изображения) не затрагивает историю диалога, поэтому подпись обрабатывать не нужно.
Q2: Как быть при вызове через совместимый API OpenAI?
При вызове Nano Banana 2 через совместимый с OpenAI сервис-прокси API от APIYI (apiyi.com) важно сохранять полный объект ответа модели из предыдущего шага и передавать его как часть истории диалога в следующем запросе. Не сохраняйте только данные изображения, отбрасывая остальные поля. Если ваш фреймворк (например, Dify или Cherry Studio) автоматически управляет историей диалога, убедитесь, что он полностью сохраняет thought_signature.
Q3: Нужно ли возвращать временные изображения с параметром thought: true?
Да, нужно. В процессе рассуждений Nano Banana 2 может возвращать временные изображения, помеченные как thought: true — это часть «процесса мышления» модели. При формировании истории диалога необходимо полностью возвращать все части (parts), полученные от модели (включая временные изображения). Самый надежный способ — просто возвращать полный объект ответа модели.
Резюме
Основные моменты, касающиеся ошибки 400 thought_signature в Nano Banana 2:
- Это не проблема безопасности контента: это требование механизма многоходовых диалогов моделей серии Gemini 3, оно не связано с
IMAGE_SAFETY. - Причина ясна: при многоходовых запросах вы не передали обратно
thought_signature, полученную от модели на предыдущем этапе. - Решение: используйте функцию чата в официальном SDK (она обрабатывает это автоматически), вручную извлекайте и возвращайте подпись или перейдите на одноходовые запросы.
Помните главное правило: не меняйте, не отбрасывайте и не пытайтесь самостоятельно конструировать thought_signature, полученную от модели — возвращайте её в исходном виде.
Если вам нужно вызывать Nano Banana 2 через сторонние платформы, рекомендуем использовать APIYI (apiyi.com). Формат ответов полностью совпадает с оригинальным API Google, стоимость составляет $0,05 за запрос, ограничений по количеству одновременных подключений нет.
📚 Справочные материалы
-
Официальная документация Google по Thought Signatures: Подробный разбор механизма «подписей мышления».
- Ссылка:
ai.google.dev/gemini-api/docs/thought-signatures - Описание: Официальная документация, включающая принципы работы, поведение моделей и способы обработки через SDK.
- Ссылка:
-
Руководство разработчика Google Gemini 3: Новые функции серии Gemini 3.
- Ссылка:
ai.google.dev/gemini-api/docs/gemini-3 - Описание: Требования к обязательной подписи и описание новых функций серии Gemini 3.
- Ссылка:
-
Документация Google по генерации изображений: Лучшие практики генерации изображений Nano Banana.
- Ссылка:
ai.google.dev/gemini-api/docs/image-generation - Описание: Рекомендации по использованию
thought_signatureпри многоэтапном редактировании изображений.
- Ссылка:
-
Документация Google Cloud Vertex AI: Описание «подписей мышления» корпоративного уровня.
- Ссылка:
docs.google.com/vertex-ai/generative-ai/docs/thought-signatures - Описание: Способы обработки и настройки подписей в среде Vertex AI.
- Ссылка:
Автор: Техническая команда APIYI
Техническое обсуждение: Приглашаем обсудить в комментариях ваш опыт реализации многоэтапного редактирования в Nano Banana 2. Дополнительные материалы доступны в центре документации APIYI по адресу docs.apiyi.com.
