Interpretando a thoughtSignature da API Nano Banana 2: por que não é uma imagem após a decodificação base64?

Nota do autor: uma análise profunda da essência do campo thoughtSignature nas respostas da API Nano Banana 2: não se trata de uma imagem, mas de uma assinatura de pensamento criptografada. Explicaremos detalhadamente a estrutura de resposta do modo Thinking, a forma correta de processá-la e os erros mais comuns.

Muitos desenvolvedores, ao invocar a API Nano Banana 2 para gerar imagens, notam que, além dos dados da imagem, a resposta contém um campo thoughtSignature — que também é uma longa string codificada em base64, parecendo dados de imagem. Após tentar decodificá-la, percebe-se que é impossível convertê-la em uma imagem. Afinal, o que é isso? Este artigo esclarecerá a natureza do thoughtSignature, por que ele não é uma imagem e como lidar com ele corretamente em diálogos de múltiplas rodadas.

Valor central: Ao terminar de ler este artigo, você entenderá o princípio técnico do thoughtSignature, evitará tratá-lo erroneamente como uma imagem e dominará a maneira correta de transmitir a assinatura em diálogos de múltiplas rodadas.

Pontos principais sobre a thoughtSignature da API Nano Banana 2

Vamos direto ao ponto com a dúvida mais frequente: a thoughtSignature não é uma imagem e não pode ser decodificada como tal; ela é uma assinatura criptografada do processo de raciocínio do modelo.

Como é a thoughtSignature na resposta da API Nano Banana 2?

Ao chamar a API Nano Banana 2 para geração de imagens, o array parts na resposta pode conter vários elementos. A estrutura típica da resposta é esta:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "Deixe-me pensar sobre como gerar esta imagem...",
          "thought": true
        },
        {
          "text": "",
          "thoughtSignature": "CpcHAdHtim9+q4rstcbvQC0ic4x1/vqQlCJ..."
        },
        {
          "inlineData": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUg..."
          }
        }
      ]
    }
  }]
}

Aqui temos três parts, que são:

1. Resumo do pensamento (thought: true): uma visão geral textual do processo de inferência do modelo.
2. Assinatura de pensamento (thoughtSignature): um snapshot criptografado do estado de inferência.
3. Dados da imagem (inlineData): os dados reais da imagem em base64.

O problema principal é que tanto a segunda quanto a terceira parte contêm dados codificados em base64. Se o seu código não fizer a distinção correta, ele tratará a thoughtSignature erroneamente como dados de imagem para decodificação — e você descobrirá que é impossível convertê-la em uma imagem.

Princípios técnicos da thoughtSignature na API Nano Banana 2

Agora que entendemos que thoughtSignature não é uma imagem, vamos analisar o que ela realmente é.

A essência da thoughtSignature

De acordo com a definição oficial do Google:

thoughtSignature (string, opcional): "Uma assinatura opaca para o pensamento, permitindo que seja reutilizada em solicitações subsequentes. Uma string codificada em base64."

Em termos simples: a thoughtSignature é um "snapshot de memória" do processo de raciocínio do modelo, retornado como uma string codificada em base64 após uma assinatura criptográfica. Sua função é permitir que o modelo "se lembre" do processo de inferência anterior em diálogos de várias rodadas, mantendo assim a coerência do pensamento.

Algumas características principais:

• Opaca: Os desenvolvedores não podem interpretar seu conteúdo e não precisam se preocupar com sua estrutura interna.
• Assinatura criptográfica: Assinada pelo servidor do Google, é impossível de falsificar — passar uma string base64 aleatória resultará em um erro de "assinatura inválida".
• Com estado: Contém a cadeia de raciocínio e os resultados de cálculos intermediários que o modelo utilizou ao gerar a resposta atual.

Diferença entre thoughtSignature e thought

Esses dois campos são frequentemente confundidos, mas são completamente diferentes:

thought é o resumo de inferência para humanos, enquanto thoughtSignature é a memória de inferência para o modelo "ler".

Por que a API Nano Banana 2 precisa da thoughtSignature?

O Nano Banana 2 pertence à série Gemini 3.1 e suporta o modo Thinking (pensamento). Antes de gerar uma imagem, o modelo realiza um raciocínio interno — analisando a intenção do comando, planejando a composição, escolhendo esquemas de cores, etc.

O estado completo desse processo de raciocínio é compactado e criptografado na thoughtSignature. Quando você realiza edições de imagem em um diálogo de várias rodadas (como "mude o fundo para azul"), o modelo precisa restaurar o estado de raciocínio anterior para entender com precisão a sua intenção de modificação.

Se você não retornar a thoughtSignature:

• Cenários de texto puro: Não gera erro, mas a qualidade da inferência e a coerência diminuem.
• Cenários de chamada de ferramenta/função: Retorna diretamente um erro HTTP 400.
• Diálogos de edição de imagem: Pode perder o contexto, resultando em edições imprecisas.

🎯 Dica de desenvolvimento: Em qualquer cenário de diálogo de várias rodadas, você deve preservar e retornar a thoughtSignature integralmente. Ao utilizar a APIYI (apiyi.com), a plataforma gerencia automaticamente a transmissão e a compatibilidade de formato da assinatura, sem que o desenvolvedor precise gerenciá-la manualmente.

Como lidar corretamente com a thoughtSignature na API Nano Banana 2

Exemplo minimalista: analisando corretamente a resposta e distinguindo imagem de assinatura

O código a seguir mostra como extrair corretamente a imagem da resposta do Nano Banana 2, salvando a thoughtSignature para uso posterior:

from google import genai
from google.genai import types

client = genai.Client(api_key="SUA_CHAVE_API")

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Desenhe um gato branco sob uma cerejeira"],
    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"Processo de pensamento: {part.text[:100]}...")
    elif hasattr(part, 'thought_signature') and part.thought_signature:
        saved_signature = part.thought_signature  # Salve, não decodifique!
        print("thoughtSignature salva (não é uma imagem)")
    elif image := part.as_image():
        image.save("gato_cerejeira.png", format="PNG")
        print("Imagem salva")

from google import genai
from google.genai import types

client = genai.Client(api_key="SUA_CHAVE_API")

# Primeira rodada: gerar imagem
response1 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Desenhe um gato branco sob uma cerejeira"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
        thinking_config=types.ThinkingConfig(
            include_thoughts=True
        ),
    )
)

# Extrair imagem e assinatura
image_data = None
thought_signature = None
model_parts = []

for part in response1.parts:
    model_parts.append(part)  # Manter as partes completas
    if hasattr(part, 'thought_signature') and part.thought_signature:
        thought_signature = part.thought_signature
    elif image := part.as_image():
        image.save("rodada1.png", format="PNG")

# Segunda rodada: editar com base no resultado anterior
# Fundamental: passe as partes completas da rodada anterior (incluindo a thoughtSignature) como histórico
history = [
    {"role": "user", "parts": [{"text": "Desenhe um gato branco sob uma cerejeira"}]},
    {"role": "model", "parts": model_parts},  # Contém a thoughtSignature
]

response2 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=history + [
        {"role": "user", "parts": [{"text": "Mude o fundo para um céu noturno e adicione a lua"}]}
    ],
    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("rodada2_editada.png", format="PNG")
        print("Imagem editada salva")

Dica: Ao utilizar o Nano Banana 2 via APIYI (apiyi.com), a plataforma fornece uma interface compatível com OpenAI que gerencia automaticamente a transmissão da thoughtSignature, eliminando a necessidade de gerenciar manualmente o estado da assinatura em diálogos de várias rodadas.

title: "Erros comuns e soluções para o thoughtSignature da API Nano Banana 2"
description: "Guia prático sobre como lidar com o campo thoughtSignature na API Nano Banana 2, evitando erros comuns e mantendo o histórico de conversação."

Erros comuns e soluções para o thoughtSignature da API Nano Banana 2

Resumo de cenários de erro

Comparação de nomenclatura do campo thoughtSignature na API Nano Banana 2

A nomenclatura do campo varia conforme o método de invocação, o que é outra armadilha comum:

Solução de emergência para a API Nano Banana 2: assinatura dummy

Se você estiver migrando um histórico de conversas antigo e não possuir um thoughtSignature válido, o Google disponibiliza um valor especial para contornar a situação:

DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

Passar essa string como valor de thoughtSignature evita o erro 400. No entanto, esta é apenas uma solução de emergência, e a coerência do raciocínio do Modelo de Linguagem Grande será afetada.

🎯 Melhor prática: Salve todos os thoughtSignature desde a primeira invocação para construir uma cadeia de histórico de conversação correta.
Se o gerenciamento manual parecer complexo demais, utilizar a interface compatível com OpenAI através da APIYI (apiyi.com) pode reduzir drasticamente a complexidade.

Perguntas Frequentes

Resumo

Pontos principais sobre a thoughtSignature na API do Nano Banana 2:

1. Não é uma imagem: thoughtSignature é uma assinatura criptografada do processo de pensamento, não dados de imagem em base64, e não pode ser decodificada em nenhum formato de imagem.
2. Deve ser reenviada exatamente como está: Salve e reenvie a thoughtSignature em conversas de múltiplas rodadas; caso contrário, a invocação do modelo resultará em erro 400 e a qualidade da conversa textual será prejudicada.
3. Diferencie corretamente os três tipos de partes: Partes com inlineData são imagens, partes com thoughtSignature são assinaturas e partes com thought: true são resumos de pensamento.

Ao compreender a natureza deste campo, você evitará cair na armadilha de tentar decodificar a assinatura como se fosse uma imagem ao processar as respostas da API do Nano Banana 2.

Recomendamos utilizar a APIYI (apiyi.com) para verificar rapidamente a funcionalidade de edição de imagem em múltiplas rodadas do Nano Banana 2. A plataforma gerencia automaticamente a transmissão da thoughtSignature, oferecendo créditos gratuitos e uma interface unificada.

📚 Referências

1. Documentação oficial do Thought Signatures: Explicação completa do Google sobre o mecanismo thoughtSignature.

   • Link: ai.google.dev/gemini-api/docs/thought-signatures
   • Descrição: Contém definições de campos, regras de transmissão e exemplos de conversas em múltiplos turnos.

2. Documentação do modo Gemini Thinking: Como ativar e configurar os parâmetros da função Thinking.

   • Link: ai.google.dev/gemini-api/docs/thinking
   • Descrição: Entenda configurações como include_thoughts e thinking_level.

3. Referência da API de inferência do Vertex AI: Definição completa dos campos do objeto Part na API REST.

   • Link: docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference
   • Descrição: Inclui definições de tipo e restrições de uso para o thoughtSignature.

4. Central de Documentação APIYI: Solução simplificada para invocar o Nano Banana 2 via interface compatível com OpenAI.

   • Link: docs.apiyi.com
   • Descrição: Processamento automático da transmissão de thoughtSignature, reduzindo a complexidade do desenvolvimento.

Autor: Equipe técnica da APIYI
Troca de conhecimentos: Sinta-se à vontade para discutir na seção de comentários. Para mais materiais, visite a central de documentação da APIYI em docs.apiyi.com