Menginterpretasikan thoughtSignature pada API Nano Banana 2: Mengapa hasil dekode base64 bukan berupa gambar?

Catatan Penulis: Analisis mendalam mengenai esensi bidang thoughtSignature dalam respons API Nano Banana 2: ini bukanlah gambar, melainkan tanda tangan pemikiran terenkripsi. Artikel ini akan mengupas tuntas struktur respons mode Thinking, cara penanganan yang benar, dan kesalahan umum yang sering terjadi.

Banyak pengembang yang saat memanggil API Nano Banana 2 untuk menghasilkan gambar, menemukan bidang thoughtSignature di dalam respons selain data gambar—bidang ini juga berupa deretan panjang kode base64 yang sekilas tampak seperti data gambar. Setelah mencoba melakukan dekode, ternyata data tersebut tidak bisa diubah menjadi gambar. Sebenarnya apa ini? Artikel ini akan menjelaskan secara tuntas esensi dari thoughtSignature, mengapa ia bukan gambar, dan bagaimana cara menanganinya dengan benar dalam percakapan multi-putaran.

Nilai Inti: Setelah membaca artikel ini, Anda akan memahami prinsip teknis thoughtSignature, menghindari kesalahan dalam memperlakukannya sebagai gambar, serta menguasai metode pengiriman tanda tangan yang tepat dalam percakapan multi-putaran.

Poin Utama thoughtSignature API Nano Banana 2

Mari kita langsung jawab pertanyaan yang paling sering muncul: thoughtSignature bukanlah gambar dan tidak bisa didekode menjadi gambar. Ini adalah tanda tangan terenkripsi dari proses berpikir model.

Seperti apa tampilan thoughtSignature dalam respons API Nano Banana 2?

Saat Anda memanggil Nano Banana 2 untuk membuat gambar, array parts dalam respons API mungkin berisi beberapa elemen. Struktur respons yang umum adalah seperti ini:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "Izinkan saya berpikir tentang cara membuat gambar ini...",
          "thought": true
        },
        {
          "text": "",
          "thoughtSignature": "CpcHAdHtim9+q4rstcbvQC0ic4x1/vqQlCJ..."
        },
        {
          "inlineData": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUg..."
          }
        }
      ]
    }
  }]
}

Ada tiga part di sini, yaitu:

1. Ringkasan pemikiran (thought: true): Ringkasan teks dari proses penalaran model.
2. Tanda tangan pemikiran (thoughtSignature): Snapshot status penalaran yang terenkripsi.
3. Data gambar (inlineData): Data base64 gambar yang sebenarnya.

Masalah utamanya adalah part ke-2 dan ke-3 sama-sama berisi data yang dikodekan dalam base64. Jika kode Anda tidak membedakannya dengan benar, Anda akan salah mengira thoughtSignature sebagai data gambar dan mencoba mendekodenya—lalu bingung mengapa gambar tersebut tidak pernah muncul.

Prinsip Teknis thoughtSignature pada API Nano Banana 2

Setelah memahami bahwa thoughtSignature bukanlah sebuah gambar, mari kita bedah apa sebenarnya komponen ini.

Hakikat thoughtSignature

Berdasarkan definisi resmi dari dokumentasi Google:

thoughtSignature (string, opsional): "Tanda tangan buram (opaque) untuk pemikiran agar dapat digunakan kembali dalam permintaan berikutnya. String yang dikodekan dalam base64."

Dalam bahasa yang lebih sederhana: thoughtSignature adalah "snapshot memori" dari proses berpikir model, yang dikembalikan dalam bentuk string base64 setelah melalui tanda tangan kriptografis. Fungsinya adalah agar model dapat "mengingat" proses penalaran sebelumnya dalam percakapan multi-putaran, sehingga menjaga alur pemikiran tetap koheren.

Beberapa karakteristik utama:

• Buram (Opaque): Pengembang tidak dapat membaca isinya dan tidak perlu memedulikan struktur internalnya.
• Tanda Tangan Kriptografis: Ditandatangani oleh server Google, sehingga tidak dapat dipalsukan—mengirimkan string base64 acak akan menghasilkan kesalahan "tanda tangan tidak valid".
• Stateful: Berisi rantai penalaran dan hasil perhitungan antara yang digunakan model saat menghasilkan jawaban saat ini.

Perbedaan antara thoughtSignature dan thought

Kedua kolom ini sering tertukar, padahal fungsinya sangat berbeda:

thought adalah ringkasan penalaran untuk dibaca manusia, sedangkan thoughtSignature adalah memori penalaran untuk "dibaca" oleh model.

Mengapa API Nano Banana 2 Memerlukan thoughtSignature

Nano Banana 2 termasuk dalam seri Gemini 3.1 yang mendukung mode Thinking (berpikir). Sebelum menghasilkan gambar, model akan melakukan penalaran internal—menganalisis niat petunjuk, merencanakan komposisi, memilih skema warna, dan sebagainya.

Status lengkap dari proses penalaran ini dikompresi dan dienkripsi menjadi thoughtSignature. Saat Anda melakukan pengeditan gambar dalam percakapan multi-putaran (misalnya, "ubah latar belakang menjadi biru"), model perlu memulihkan status penalaran sebelumnya agar dapat memahami niat perubahan Anda dengan akurat.

Jika Anda tidak mengirimkan kembali thoughtSignature:

• Skenario teks murni: Tidak ada kesalahan, tetapi kualitas dan koherensi penalaran akan menurun.
• Skenario pemanggilan alat/fungsi: Langsung mengembalikan kesalahan HTTP 400.
• Percakapan multi-putaran pengeditan gambar: Konteks mungkin hilang, dan hasil pengeditan menjadi tidak akurat.

🎯 Saran Pengembangan: Dalam skenario percakapan multi-putaran apa pun, Anda harus menyimpan dan mengirimkan kembali thoughtSignature secara utuh.
Saat menggunakan APIYI (apiyi.com), platform akan menangani pengiriman tanda tangan dan kompatibilitas format secara otomatis, sehingga pengembang tidak perlu mengelolanya secara manual.

Cara Menangani thoughtSignature API Nano Banana 2 dengan Benar

Contoh Sederhana: Mengurai respons dan membedakan gambar dengan tanda tangan

Kode berikut menunjukkan cara mengekstrak gambar dari respons Nano Banana 2 dengan benar, sekaligus menyimpan thoughtSignature untuk penggunaan selanjutnya:

from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Gambar seekor kucing putih di bawah pohon sakura"],
    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"Proses berpikir: {part.text[:100]}...")
    elif hasattr(part, 'thought_signature') and part.thought_signature:
        saved_signature = part.thought_signature  # Simpan, jangan didekode!
        print("thoughtSignature berhasil disimpan (bukan gambar)")
    elif image := part.as_image():
        image.save("kucing_sakura.png", format="PNG")
        print("Gambar berhasil disimpan")

from google import genai
from google.genai import types

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

# Putaran pertama: Menghasilkan gambar
response1 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Gambar seekor kucing putih di bawah pohon sakura"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(image_size="2K"),
        thinking_config=types.ThinkingConfig(
            include_thoughts=True
        ),
    )
)

# Ekstrak gambar dan tanda tangan
image_data = None
thought_signature = None
model_parts = []

for part in response1.parts:
    model_parts.append(part)  # Simpan parts lengkap
    if hasattr(part, 'thought_signature') and part.thought_signature:
        thought_signature = part.thought_signature
    elif image := part.as_image():
        image.save("putaran1.png", format="PNG")

# Putaran kedua: Mengedit berdasarkan hasil sebelumnya
# Kunci: Masukkan parts lengkap dari putaran sebelumnya (termasuk thoughtSignature) sebagai riwayat
history = [
    {"role": "user", "parts": [{"text": "Gambar seekor kucing putih di bawah pohon sakura"}]},
    {"role": "model", "parts": model_parts},  # Berisi thoughtSignature
]

response2 = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=history + [
        {"role": "user", "parts": [{"text": "Ubah latar belakang menjadi langit malam, tambahkan bulan"}]}
    ],
    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("putaran2_edit.png", format="PNG")
        print("Gambar hasil edit berhasil disimpan")

Saran: Saat memanggil Nano Banana 2 melalui APIYI (apiyi.com), platform menyediakan antarmuka format yang kompatibel dengan OpenAI, yang secara otomatis menangani pengiriman thoughtSignature sehingga Anda tidak perlu mengelola status tanda tangan dalam percakapan multi-putaran secara manual.

Jebakan Umum dan Solusi thoughtSignature pada API Nano Banana 2

Ringkasan Skenario Masalah

Perbandingan Penamaan Field thoughtSignature pada API Nano Banana 2

Penamaan field yang berbeda tergantung metode pemanggilan sering menjadi jebakan:

Solusi Darurat API Nano Banana 2: Tanda tangan dummy

Jika Anda sedang memigrasikan riwayat percakapan lama dan tidak memiliki thoughtSignature yang valid, Google menyediakan nilai bypass khusus:

# Nilai dummy untuk bypass validasi tanda tangan
DUMMY_SIGNATURE = "context_engineering_is_the_way_to_go"

Menggunakan string ini sebagai nilai thoughtSignature dapat mencegah error 400. Namun, ini hanya solusi darurat dan dapat memengaruhi koherensi penalaran model.

🎯 Praktik Terbaik: Simpan semua thoughtSignature secara lengkap sejak pemanggilan pertama untuk membangun rantai riwayat percakapan yang benar.
Jika manajemen manual terasa rumit, gunakan antarmuka yang kompatibel dengan OpenAI melalui APIYI (apiyi.com) untuk menyederhanakan prosesnya.

Pertanyaan Umum

Kesimpulan

Poin-poin utama mengenai thoughtSignature dalam API Nano Banana 2:

1. Bukan gambar: thoughtSignature adalah tanda tangan proses penalaran yang terenkripsi, bukan data gambar base64, dan tidak dapat didekode menjadi format gambar apa pun.
2. Harus dikirim kembali apa adanya: Simpan dan kirim kembali thoughtSignature apa adanya dalam percakapan multi-putaran. Jika tidak, pemanggilan fungsi akan menghasilkan kesalahan 400 dan kualitas percakapan teks akan menurun.
3. Bedakan tiga jenis part dengan benar: Part dengan inlineData adalah gambar, part dengan thoughtSignature adalah tanda tangan, dan part dengan thought: true adalah ringkasan pemikiran.

Setelah memahami esensi field ini, Anda tidak akan lagi terjebak dalam kesalahan "mendekode tanda tangan sebagai gambar" saat mengurai respons API Nano Banana 2.

Direkomendasikan untuk menggunakan APIYI (apiyi.com) guna memvalidasi fitur pengeditan gambar multi-putaran Nano Banana 2 dengan cepat. Platform ini menangani pengiriman thoughtSignature secara otomatis, menyediakan kuota gratis, dan antarmuka yang terpadu.

📚 Referensi

1. Dokumentasi Resmi Thought Signatures: Penjelasan lengkap Google mengenai mekanisme thoughtSignature

   • Tautan: ai.google.dev/gemini-api/docs/thought-signatures
   • Keterangan: Berisi definisi field, aturan transmisi, dan contoh percakapan multi-putaran

2. Dokumentasi Mode Thinking Gemini: Cara mengaktifkan fitur Thinking dan parameter konfigurasinya

   • Tautan: ai.google.dev/gemini-api/docs/thinking
   • Keterangan: Memahami konfigurasi seperti include_thoughts, thinking_level, dan lainnya

3. Referensi API Inferensi Vertex AI: Definisi field lengkap untuk objek Part dalam REST API

   • Tautan: docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference
   • Keterangan: Berisi definisi tipe dan batasan penggunaan thoughtSignature

4. Pusat Dokumentasi APIYI: Solusi sederhana untuk memanggil Nano Banana 2 melalui antarmuka yang kompatibel dengan OpenAI

   • Tautan: docs.apiyi.com
   • Keterangan: Menangani transmisi thoughtSignature secara otomatis, mengurangi kompleksitas pengembangan

Penulis: Tim Teknis APIYI
Diskusi Teknis: Silakan berdiskusi di kolom komentar, untuk materi lebih lanjut kunjungi pusat dokumentasi APIYI di docs.apiyi.com