Nota do autor: Está recebendo o erro "Image part is missing a thought_signature" no Nano Banana 2? Isso é um erro 400 causado pela falta de retorno da assinatura de pensamento em conversas de múltiplos turnos. Este artigo detalha a causa, as soluções e exemplos de código.
Se você recebeu este erro ao editar imagens usando o 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."
}
}
Não entre em pânico — este é um requisito do mecanismo de diálogo de múltiplos turnos da série Gemini 3, e não um problema de segurança de conteúdo ou falha da plataforma. Em termos simples: você enviou uma imagem gerada anteriormente na segunda rodada da solicitação, mas não incluiu o thought_signature (assinatura de pensamento) associado a essa imagem.
Valor principal: Ao terminar de ler este artigo, você entenderá como o thought_signature funciona, dominará 3 soluções e aprenderá a lidar corretamente com assinaturas de pensamento em cenários de edição de imagem de múltiplos turnos.
Decifrando o erro de thought_signature no Nano Banana 2
O que esse erro significa exatamente?
Vamos decompor essa mensagem de erro parte por parte:
| Campo | Significado | Explicação |
|---|---|---|
| status_code: 400 | Erro de parâmetro na requisição | Não é um erro do servidor, mas sim um problema nos parâmetros enviados pelo cliente |
| Image part | Dados de imagem incluídos na requisição | Você enviou uma imagem na 2ª rodada da requisição |
| missing a thought_signature | Falta a assinatura de pensamento | Esta imagem foi gerada pelo modelo na rodada anterior e precisa vir acompanhada da assinatura |
| content position 2, part position 1 | 2ª mensagem do histórico (resposta do modelo), 1ª parte | Localiza precisamente onde a assinatura está faltando |
Resumo em uma frase: A API do Gemini é stateless (sem estado), e o modelo utiliza a thought_signature (assinatura de pensamento) para manter o contexto de raciocínio entre várias rodadas de conversa. Ao iniciar uma segunda rodada de edição de imagem, você deve reenviar a thought_signature retornada pelo modelo na rodada anterior exatamente como ela veio, caso contrário, receberá um erro 400.
Por que a série Gemini 3 exige obrigatoriamente a thought_signature?
| Comparação | Série Gemini 2.x | Série Gemini 3 (inclui NB2) |
|---|---|---|
| Assinatura de pensamento | Opcional em alguns cenários | Obrigatória para todos os tipos de part |
| Rigidez da validação | Flexível | Estrita (falta resulta em erro 400) |
| Escopo de aplicação | Principalmente para chamadas de função | Texto, imagem e chamadas de função |
| Processamento automático | SDK oficial trata automaticamente | SDK oficial trata automaticamente |
A série de modelos Gemini 3 (incluindo o gemini-3.1-flash, base do Nano Banana 2) exige a assinatura de pensamento pelos seguintes motivos:
- Restauração do estado de raciocínio: A assinatura de pensamento é uma representação criptografada do processo interno de raciocínio do modelo, permitindo que ele recupere seu "estado de pensamento" anterior na rodada seguinte.
- Continuidade na edição de imagens: Para edições de imagem em múltiplas rodadas, o modelo precisa entender que "esta imagem foi gerada por mim no passo anterior" para executar a instrução de edição corretamente.
- Segurança e consistência: O mecanismo de assinatura garante que o histórico da conversa não foi adulterado, aumentando a confiabilidade das interações.
🎯 Conceito chave: Este erro 400 não tem relação alguma com políticas de segurança de conteúdo (IMAGE_SAFETY), nem é um problema da plataforma APIYI. É um requisito normal do mecanismo da série Gemini 3 que precisa ser tratado no nível do código.
3 soluções para corrigir o erro de thought_signature no Nano Banana 2
Solução 1: Usar a função chat do SDK oficial (Recomendado)
Se você utiliza o SDK oficial do Google (Python / Node.js / Java), a maneira mais simples é usar a função chat, pois o SDK gerencia a thought_signature automaticamente:
from google import genai
client = genai.Client(api_key="SUA_CHAVE_API")
# Use a função chat, o SDK gerencia a thought_signature automaticamente
chat = client.chats.create(model="gemini-3.1-flash-image-preview")
# 1ª rodada: Gerar imagem
response1 = chat.send_message("Desenhe um gato laranja sentado no parapeito da janela")
# 2ª rodada: Editar imagem (a assinatura é reenviada automaticamente)
response2 = chat.send_message("Coloque um gorro de Natal no gato")
Solução 2: Extrair e reenviar manualmente a thought_signature
Se você usa chamadas HTTP personalizadas ou através de uma interface compatível com OpenAI, precisará lidar com a assinatura manualmente. A lógica principal é: extrair a thought_signature da resposta da rodada anterior e incluí-la exatamente como está na parte correspondente da requisição seguinte.
import openai
client = openai.OpenAI(
api_key="SUA_CHAVE_API",
base_url="https://vip.apiyi.com/v1"
)
# 1ª rodada: Gerar imagem
response1 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[{"role": "user", "content": "Desenhe um gato laranja"}]
)
# Fundamental: Salve a resposta completa do modelo
# Incluindo os dados da imagem e a thought_signature
model_reply = response1.choices[0].message
# 2ª rodada: Editar imagem
# Passe a resposta completa do modelo como parte do histórico da conversa
response2 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[
{"role": "user", "content": "Desenhe um gato laranja"},
model_reply, # Reenvio completo, incluindo a thought_signature
{"role": "user", "content": "Coloque um chapéu no gato"}
]
)
Solução 3: Mudar para requisições de rodada única
Se o seu cenário não exige edição em múltiplas rodadas, você pode enviar requisições independentes a cada vez, evitando completamente o problema da thought_signature:
# Edição de imagem em rodada única: Envie diretamente a imagem original + instrução de edição
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": "Coloque um gorro de Natal neste gato"}
]
}]
)
🎯 Recomendação: Para novos projetos, sugerimos a Solução 1 (função
chatdo SDK oficial). Projetos existentes podem escolher a Solução 2 ou 3 dependendo do esforço de refatoração. Ao realizar a invocação do modelo Nano Banana 2 via APIYI (apiyi.com), as soluções 2 e 3 funcionarão perfeitamente.
Mitos comuns sobre o thought_signature do Nano Banana 2
| Mito | Fato |
|---|---|
| É um problema de segurança de conteúdo | Não. O erro 400 indica falha na validação de parâmetros, não tem relação com IMAGE_SAFETY |
| É um problema da plataforma de API | Não. É um requisito de mecanismo dos modelos da série Gemini 3 |
| Posso construir minha própria assinatura | Não. A assinatura é criptografada; você deve retornar exatamente o valor enviado pelo modelo |
| Apenas chamadas de função precisam disso | Todos os tipos de "part" da série Gemini 3 podem exigir |
Configurar thinking: off resolve |
Não. Mesmo com o nível de pensamento em "minimal", a assinatura ainda será retornada e deve ser reenviada |
Localização do thought_signature na resposta do Nano Banana 2
Nos dados de resposta do Nano Banana 2, você deve prestar atenção a dois tipos especiais de "part":
Imagens temporárias (thought: true): Imagens intermediárias geradas durante o processo de raciocínio do modelo, marcadas como thought: true. São dados temporários e não precisam ser exibidos ao usuário.
Imagem final (contendo thought_signature): A imagem gerada final conterá um campo thought_signature. Esta é a assinatura que você precisa reenviar na próxima rodada de solicitação.
{
"candidates": [{
"content": {
"parts": [
{
"inlineData": {"mimeType": "image/png", "data": "..."},
"thought_signature": "CkYKRAo..."
}
]
}
}]
}
🎯 Detalhes técnicos: O
thought_signatureé uma string criptografada com comprimento geralmente entre 200 e 500 caracteres. Não tente analisar, modificar ou construir a sua própria — receba e reenvie exatamente como está. Ao realizar a invocação do modelo via APIYI (apiyi.com), o formato da resposta é exatamente igual ao da API nativa do Google.
Lista de verificação de erros do thought_signature no Nano Banana 2
4 passos para uma verificação rápida:
- Confirme se é uma solicitação de múltiplas rodadas: Se o seu array
messagescontiver respostas anteriores do papel de modelo (especialmente dados de imagem), então é uma solicitação de múltiplas rodadas. - Verifique se a resposta completa foi salva: A resposta retornada pelo modelo na rodada anterior contém o campo
thought_signature? Foi salva integralmente? - Verifique se a assinatura foi modificada: Durante a serialização/desserialização JSON, a string da assinatura foi truncada ou escapada?
- Verifique o alinhamento da posição do "part": A mensagem de erro contendo
content position X, part position Ypode ajudá-lo a localizar exatamente qual "part" está sem a assinatura.
Perguntas Frequentes
Q1: A geração de imagem de turno único também apresenta esse erro?
Geralmente não. O erro thought_signature ocorre quase exclusivamente em conversas multimodais — ele é disparado quando você insere a imagem retornada pelo modelo em um histórico de conversas e envia uma nova solicitação. Tarefas de texto para imagem ou imagem para imagem de turno único (enviando a imagem original diretamente) não envolvem o histórico de conversas e não precisam processar assinaturas.
Q2: Como lidar com isso ao chamar via interface compatível com OpenAI?
Ao chamar o Nano Banana 2 através da interface compatível com OpenAI da APIYI (apiyi.com), o segredo é salvar o objeto completo da resposta do modelo do turno anterior e passá-lo como histórico de conversas na próxima solicitação. Não salve apenas os dados da imagem descartando outros campos. Se o seu framework (como Dify ou Cherry Studio) gerencia o histórico de conversas automaticamente, verifique se ele mantém o thought_signature intacto.
Q3: As imagens temporárias com `thought: true` precisam ser reenviadas?
Sim. Durante o processo de inferência, o Nano Banana 2 pode retornar imagens temporárias marcadas como thought: true, que fazem parte do "processo de pensamento" do modelo. Ao construir o histórico de conversas, todas as partes retornadas pelo modelo (incluindo as imagens temporárias) devem ser reenviadas integralmente. A prática mais segura é reenviar o objeto de resposta completo do modelo.
Resumo
Pontos principais sobre o erro 400 thought_signature do Nano Banana 2:
- Não é um problema de segurança de conteúdo: Este é um requisito do mecanismo de conversação multimodal da série Gemini 3, não tem relação com
IMAGE_SAFETY. - Causa clara: Em solicitações multimodais, o
thought_signatureretornado pelo modelo no turno anterior não foi reenviado exatamente como estava. - Solução: Use a função de chat do SDK oficial (que processa isso automaticamente), extraia e reenvie a assinatura manualmente ou mude para solicitações de turno único.
Lembre-se da regra de ouro: não modifique, não descarte e não tente construir o thought_signature por conta própria — reenvie exatamente o que você recebeu.
Se precisar chamar o Nano Banana 2 através de plataformas de terceiros, recomendamos a APIYI (apiyi.com), que oferece um formato de resposta totalmente consistente com a API nativa do Google, por $0,05/chamada e sem limite de concorrência.
📚 Referências
-
Documentação oficial do Google sobre Assinaturas de Pensamento (Thought Signatures): Detalhes sobre o mecanismo de assinatura de pensamento
- Link:
ai.google.dev/gemini-api/docs/thought-signatures - Descrição: Documentação oficial, incluindo princípios de funcionamento, comportamento do modelo e métodos de processamento do SDK
- Link:
-
Guia do Desenvolvedor do Google Gemini 3: Novos recursos da série Gemini 3
- Link:
ai.google.dev/gemini-api/docs/gemini-3 - Descrição: Requisitos obrigatórios de assinatura e explicações sobre as novas funcionalidades da série Gemini 3
- Link:
-
Documentação de geração de imagens do Google: Melhores práticas para geração de imagens com Nano Banana
- Link:
ai.google.dev/gemini-api/docs/image-generation - Descrição: Sugestões de uso de
thought_signatureem edições de imagem de múltiplas rodadas
- Link:
-
Documentação do Google Cloud Vertex AI: Explicação sobre assinaturas de pensamento de nível empresarial
- Link:
docs.google.com/vertex-ai/generative-ai/docs/thought-signatures - Descrição: Métodos de processamento e configuração de assinaturas em ambientes Vertex AI
- Link:
Autor: Equipe técnica da APIYI
Troca de conhecimentos: Sinta-se à vontade para discutir suas experiências com a edição de múltiplas rodadas do Nano Banana 2 na seção de comentários. Para mais materiais, visite a central de documentação da APIYI em docs.apiyi.com
