Catatan Penulis: Mengalami error "Image part is missing a thought_signature" pada Nano Banana 2? Ini adalah error 400 yang terjadi karena tanda tangan pemikiran (thought_signature) tidak dikirimkan kembali saat percakapan multi-putaran. Artikel ini akan membahas penyebab, solusi perbaikan, dan contoh kodenya secara mendetail.
Jika Anda menerima pesan error seperti ini saat melakukan pengeditan gambar menggunakan 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."
}
}
Jangan panik—ini adalah persyaratan mekanisme percakapan multi-putaran dari model seri Gemini 3, bukan masalah keamanan konten atau kegagalan platform. Sederhananya: Anda mengirimkan gambar yang dihasilkan sebelumnya pada putaran kedua, tetapi tidak menyertakan thought_signature (tanda tangan pemikiran) dari gambar tersebut.
Nilai Utama: Setelah membaca artikel ini, Anda akan memahami cara kerja thought_signature, menguasai 3 solusi perbaikan, dan mempelajari cara menangani tanda tangan pemikiran dengan benar dalam skenario pengeditan gambar multi-putaran.
Analisis Mendalam Error thought_signature pada Nano Banana 2
Apa Sebenarnya Arti Error Ini?
Mari kita bedah pesan error tersebut kata demi kata:
| Field | Arti | Penjelasan |
|---|---|---|
| status_code: 400 | Error parameter permintaan | Bukan error server, melainkan masalah parameter dari sisi klien |
| Image part | Data gambar dalam permintaan | Anda mengirimkan gambar pada permintaan putaran ke-2 |
| missing a thought_signature | Tanda tangan pemikiran hilang | Gambar ini dihasilkan oleh model di putaran sebelumnya, perlu menyertakan tanda tangan |
| content position 2, part position 1 | Pesan ke-2 dalam riwayat chat, part ke-1 | Lokasi tepat di mana tanda tangan tersebut hilang |
Ringkasan dalam satu kalimat: API Gemini bersifat stateless (tanpa status). Model menggunakan thought_signature (tanda tangan pemikiran) untuk mempertahankan konteks penalaran antar putaran percakapan. Saat Anda memulai permintaan pengeditan gambar putaran kedua, Anda wajib mengirimkan kembali thought_signature yang dikembalikan oleh model pada putaran sebelumnya. Jika tidak, Anda akan menerima error 400.
Mengapa Seri Gemini 3 Mewajibkan thought_signature
| Perbandingan | Seri Gemini 2.x | Seri Gemini 3 (termasuk NB2) |
|---|---|---|
| Tanda tangan pemikiran | Opsional di beberapa skenario | Wajib untuk semua tipe part |
| Tingkat verifikasi | Longgar | Ketat (hilang = 400) |
| Cakupan | Terutama untuk pemanggilan fungsi | Berlaku untuk teks, gambar, dan fungsi |
| Penanganan otomatis | SDK resmi menangani otomatis | SDK resmi menangani otomatis |
Model seri Gemini 3 (termasuk gemini-3.1-flash yang menjadi basis Nano Banana 2) mewajibkan tanda tangan pemikiran karena:
- Pemulihan status penalaran: Tanda tangan pemikiran adalah representasi terenkripsi dari proses penalaran internal model, memungkinkan model memulihkan "status berpikir" sebelumnya di putaran percakapan berikutnya.
- Kontinuitas pengeditan gambar: Untuk pengeditan gambar multi-putaran, model perlu memahami bahwa "gambar ini dihasilkan oleh saya di langkah sebelumnya" agar dapat menjalankan instruksi pengeditan dengan benar.
- Keamanan dan konsistensi: Mekanisme tanda tangan memastikan riwayat percakapan tidak diubah, meningkatkan keandalan interaksi multi-putaran.
🎯 Pemahaman Kunci: Error 400 ini sama sekali tidak terkait dengan kebijakan keamanan konten (IMAGE_SAFETY) dan bukan masalah pada platform APIYI. Ini adalah persyaratan mekanisme normal dari model seri Gemini 3 yang harus ditangani dengan benar di level kode.
3 Solusi untuk Memperbaiki Error thought_signature pada Nano Banana 2
Solusi 1: Gunakan fitur chat SDK resmi (Direkomendasikan)
Jika Anda menggunakan SDK resmi Google (Python / Node.js / Java), cara termudah adalah menggunakan fitur chat, karena SDK akan mengelola thought_signature secara otomatis:
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
# Gunakan fitur chat, SDK menangani thought_signature secara otomatis
chat = client.chats.create(model="gemini-3.1-flash-image-preview")
# Putaran 1: Menghasilkan gambar
response1 = chat.send_message("Gambar seekor kucing oranye duduk di ambang jendela")
# Putaran 2: Mengedit gambar (signature dikirim kembali secara otomatis)
response2 = chat.send_message("Berikan kucing itu topi Natal")
Solusi 2: Ekstrak dan kirim kembali thought_signature secara manual
Jika Anda menggunakan panggilan HTTP kustom atau melalui antarmuka yang kompatibel dengan OpenAI, Anda perlu menangani tanda tangan secara manual. Logika kuncinya adalah: Ekstrak thought_signature dari respons putaran sebelumnya, dan sertakan apa adanya di part yang sesuai pada permintaan berikutnya.
import openai
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://vip.apiyi.com/v1"
)
# Putaran 1: Menghasilkan gambar
response1 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[{"role": "user", "content": "Gambar seekor kucing oranye"}]
)
# Kunci: Simpan respons model yang lengkap
# Termasuk data gambar dan thought_signature
model_reply = response1.choices[0].message
# Putaran 2: Mengedit gambar
# Masukkan respons model lengkap dari putaran sebelumnya sebagai riwayat percakapan
response2 = client.chat.completions.create(
model="gemini-3.1-flash-image-preview",
messages=[
{"role": "user", "content": "Gambar seekor kucing oranye"},
model_reply, # Kirim kembali secara lengkap, termasuk thought_signature
{"role": "user", "content": "Berikan kucing itu topi"}
]
)
Solusi 3: Gunakan permintaan satu putaran
Jika skenario Anda tidak memerlukan pengeditan percakapan multi-putaran, Anda dapat mengirim permintaan satu putaran yang independen setiap saat untuk menghindari masalah thought_signature sepenuhnya:
# Pengeditan gambar satu putaran: Langsung masukkan gambar asli + instruksi pengeditan
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": "Berikan kucing ini topi Natal"}
]
}]
)
🎯 Rekomendasi: Untuk proyek baru, disarankan menggunakan Solusi 1 (fitur chat SDK resmi). Untuk proyek yang sudah ada, Anda dapat memilih Solusi 2 atau 3 tergantung pada skala perubahan yang diperlukan. Saat melakukan pemanggilan Nano Banana 2 melalui platform APIYI (apiyi.com), Solusi 2 dan 3 dapat berfungsi dengan normal.
Miskonsepsi Umum tentang thought_signature Nano Banana 2
| Miskonsepsi | Fakta |
|---|---|
| Ini masalah keamanan konten | Bukan. Error 400 adalah kegagalan validasi parameter, tidak ada hubungannya dengan IMAGE_SAFETY |
| Ini masalah platform API | Bukan. Ini adalah persyaratan mekanisme model seri Gemini 3 |
| Bisa membuat tanda tangan sendiri | Tidak bisa. Tanda tangan dienkripsi, harus mengembalikan nilai yang dikembalikan model apa adanya |
| Hanya diperlukan untuk pemanggilan fungsi | Semua tipe part pada seri Gemini 3 mungkin memerlukannya |
Mengatur thinking: off bisa menghindarinya |
Tidak bisa. Meskipun level thinking diatur ke minimal, tanda tangan tetap akan dikembalikan dan wajib dikembalikan |
Lokasi thought_signature dalam Respons Nano Banana 2
Dalam data respons Nano Banana 2, perhatikan dua jenis part khusus berikut:
Gambar Sementara (thought: true): Gambar perantara yang dihasilkan selama proses inferensi model, ditandai sebagai thought: true. Ini adalah data sementara dan tidak perlu ditampilkan kepada pengguna.
Gambar Akhir (termasuk thought_signature): Gambar yang dihasilkan akhirnya akan berisi kolom thought_signature. Inilah tanda tangan yang harus Anda kembalikan dalam permintaan putaran berikutnya.
{
"candidates": [{
"content": {
"parts": [
{
"inlineData": {"mimeType": "image/png", "data": "..."},
"thought_signature": "CkYKRAo..."
}
]
}
}]
}
🎯 Detail Teknis:
thought_signatureadalah string terenkripsi dengan panjang biasanya antara 200-500 karakter. Jangan mencoba mengurai, memodifikasi, atau membuatnya sendiri—terima apa adanya dan kembalikan apa adanya. Saat melakukan pemanggilan melalui APIYI apiyi.com, format responsnya sepenuhnya konsisten dengan API asli Google.
Daftar Periksa Kesalahan thought_signature Nano Banana 2
4 Langkah Pemeriksaan Cepat:
- Konfirmasi apakah ini permintaan multi-putaran: Jika array
messagesAnda berisi balasan peran model sebelumnya (terutama data gambar), maka itu adalah permintaan multi-putaran. - Periksa apakah respons lengkap telah disimpan: Apakah respons yang dikembalikan model pada putaran sebelumnya berisi kolom
thought_signature? Apakah disimpan secara utuh? - Periksa apakah tanda tangan telah dimodifikasi: Selama proses serialisasi/deserialisasi JSON, apakah string tanda tangan terpotong atau mengalami escape?
- Periksa penyelarasan posisi part:
content position X, part position Ydalam pesan kesalahan dapat membantu Anda menentukan secara tepat part mana yang kehilangan tanda tangan.
Pertanyaan Umum
Q1: Apakah pembuatan gambar satu putaran juga akan mengalami error ini?
Biasanya tidak. Error thought_signature hampir hanya muncul dalam percakapan multi-putaran—yaitu saat Anda memasukkan gambar yang dikembalikan oleh model sebelumnya ke dalam riwayat percakapan dan mengirimkan permintaan baru. Pembuatan gambar teks ke gambar atau gambar ke gambar satu putaran (yang langsung menyertakan gambar asli) tidak melibatkan riwayat percakapan, sehingga tidak perlu menangani tanda tangan (signature).
Q2: Bagaimana cara menanganinya saat memanggil melalui antarmuka yang kompatibel dengan OpenAI?
Saat memanggil Nano Banana 2 melalui antarmuka yang kompatibel dengan OpenAI dari APIYI (apiyi.com), kuncinya adalah menyimpan objek lengkap dari respons model pada putaran sebelumnya, lalu mengirimkannya kembali sebagai riwayat percakapan pada permintaan berikutnya. Jangan hanya menyimpan data gambar dan membuang kolom lainnya. Jika framework Anda (seperti Dify atau Cherry Studio) mengelola riwayat percakapan secara otomatis, pastikan framework tersebut menyimpan thought_signature secara utuh.
Q3: Apakah gambar sementara dengan `thought: true` perlu dikirim balik?
Ya, perlu. Selama proses inferensi, Nano Banana 2 mungkin mengembalikan gambar sementara yang ditandai sebagai thought: true. Ini adalah bagian dari "proses berpikir" model. Saat menyusun riwayat percakapan, semua bagian (part) yang dikembalikan oleh model (termasuk gambar sementara) harus dikirim balik secara lengkap. Cara paling aman adalah dengan mengirim balik seluruh objek respons model.
Kesimpulan
Poin utama mengenai error 400 thought_signature pada Nano Banana 2:
- Bukan masalah keamanan konten: Ini adalah persyaratan mekanisme percakapan multi-putaran model seri Gemini 3, tidak ada hubungannya dengan IMAGE_SAFETY.
- Penyebab jelas: Saat melakukan permintaan multi-putaran,
thought_signatureyang dikembalikan oleh model pada putaran sebelumnya tidak dikirim balik apa adanya. - Solusi perbaikan: Gunakan fungsi chat SDK resmi (yang menangani secara otomatis), ekstrak dan kirim balik tanda tangan secara manual, atau gunakan permintaan satu putaran.
Ingat prinsip utamanya: Jangan mengubah, jangan membuang, dan jangan membuat sendiri thought_signature yang dikembalikan oleh model—kirim balik apa pun yang Anda terima.
Jika Anda perlu memanggil Nano Banana 2 melalui platform pihak ketiga, kami merekomendasikan APIYI (apiyi.com). Format responsnya sepenuhnya konsisten dengan API asli Google, dengan harga $0,05/permintaan dan tanpa batasan konkurensi.
📚 Referensi
-
Dokumentasi Resmi Google Thought Signatures: Penjelasan mendalam tentang mekanisme tanda tangan pemikiran (thought signatures)
- Tautan:
ai.google.dev/gemini-api/docs/thought-signatures - Keterangan: Dokumentasi resmi yang mencakup cara kerja, perilaku model, dan metode penanganan SDK.
- Tautan:
-
Panduan Pengembang Google Gemini 3: Fitur baru seri Gemini 3
- Tautan:
ai.google.dev/gemini-api/docs/gemini-3 - Keterangan: Penjelasan mengenai persyaratan tanda tangan wajib dan fitur baru pada seri Gemini 3.
- Tautan:
-
Dokumentasi Pembuatan Gambar Google: Praktik terbaik pembuatan gambar Nano Banana
- Tautan:
ai.google.dev/gemini-api/docs/image-generation - Keterangan: Saran penggunaan
thought_signaturedalam pengeditan gambar multi-putaran.
- Tautan:
-
Dokumentasi Google Cloud Vertex AI: Penjelasan tanda tangan pemikiran tingkat perusahaan
- Tautan:
docs.google.com/vertex-ai/generative-ai/docs/thought-signatures - Keterangan: Metode penanganan dan konfigurasi tanda tangan di lingkungan Vertex AI.
- Tautan:
Penulis: Tim Teknis APIYI
Diskusi Teknis: Mari berdiskusi di kolom komentar mengenai pengalaman implementasi pengeditan multi-putaran Nano Banana 2. Untuk informasi lebih lanjut, silakan kunjungi pusat dokumentasi APIYI di docs.apiyi.com.
