Prompt AI JSON terstruktur Gemini adalah cara meminta model Gemini mengembalikan keluaran dalam format JSON yang konsisten, lengkap dengan tipe data dan kunci yang kamu tentukan sendiri. Pendekatan ini menggantikan kebiasaan lama “minta tolong jawab dalam format JSON” yang hasilnya acak dan susah di-parse.
Tutorial ini memakai panduan Structured Output resmi Google dan dokumentasi Interactions API yang menjadi antarmuka default Gemini sejak Juni 2026. Sumber dibaca pada 14 September 2026. 💡
Mengapa JSON terstruktur lebih aman?
Tanpa struktur eksplisit, model bisa menjawab dengan paragraf, daftar, atau teks campuran. Kode yang menerima output harus menebak-nebak format, melakukan banyak string slicing, atau menulis regex panjang. Saat model diganti atau diperbarui, perilaku sering bergeser dan kode kamu bisa rusak diam-diam.
Dengan JSON Schema, kamu memberi tahu model: “kembalikan objek dengan kunci A, B, C, masing-masing bertipe tertentu, dan tidak ada kunci lain.” Model yang didukung akan menaatinya karena output diverifikasi server-side sebelum sampai ke aplikasi kamu. Hasilnya, kode di sisi klien cukup melakukan parsing ringan dan validasi tipe.
Prasyarat singkat
Sebelum mulai, pastikan hal-hal berikut:
- Akun Google AI Studio atau Vertex AI yang sudah mengaktifkan Gemini API.
- API key yang disimpan di environment variable, bukan di kode.
- SDK Python
google-genaiatau SDK JavaScript@google/genai; REST murni juga bisa. - Library validasi Pydantic (Python) atau Zod (TypeScript) untuk cek tipe sisi klien.
- Pemahaman dasar JSON, enum, dan array of object.
Pemula yang baru belajar integrasi API bisa sambil membaca konsep umum lewat koleksi source code sistem website dari Kuskuskuy sebagai referensi pola request/response di proyek nyata. Produk tersebut adalah resource komersial terpisah, bukan bagian dari Gemini API. 🔍
Anatomi request JSON Schema
Bagian inti dari prompt AI JSON terstruktur di Gemini API adalah kolom response_format. Pada Interactions API, kamu menulisnya seperti ini:
response_format = { "type": "text", "mime_type": "application/json", "schema": <json_schema_di_sini>}Schema yang diterima mengikuti subset JSON Schema. Tipe yang didukung antara lain string, number, integer, boolean, object, array, dan null. Untuk object, gunakan properties dan required. Untuk string, manfaatkan enum saat opsi jawaban terbatas, dan format jika kamu ingin pola tertentu seperti date-time. 📌
Contoh schema sederhana
{ "type": "object", "properties": { "recipe_name": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "string" } }, "prep_time_minutes": { "type": "integer" } }, "required": ["recipe_name", "ingredients"]}Schema ini meminta model mengembalikan objek dengan kunci recipe_name, ingredients, dan prep_time_minutes. recipe_name dan ingredients wajib; prep_time_minutes opsional. Kunci lain yang tidak dideklarasikan biasanya tidak muncul, sehingga data lebih mudah dipercaya.
Contoh prompt siap salin
Berikut pola yang bisa kamu salin dan ubah sesuai kasus. Prinsipnya: prompt eksplisit, schema jelas, dan output yang diharapkan spesifik.
1. Ekstraksi data dari teks bebas
interaction = client.interactions.create( model="gemini-3.8-flash", input="Ekstrak data dari teks berikut dan kembalikan JSON valid.\n\nTeks: 'Pisang 3 buah, mentega 1/3 cup, gula 3/4 cup, telur 1, vanili 1 sdt, soda kue 1 sdt, garam sedikit, tepung 1.5 cup.'", response_format={ "type": "text", "mime_type": "application/json", "schema": <schema_resep_di_atas> },)Hasilnya adalah string JSON. Parse dengan JSON.parse() di JavaScript atau json.loads() di Python sebelum dipakai. ⚙️
2. Klasifikasi ke enum terbatas
schema = { "type": "object", "properties": { "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] }, "summary": { "type": "string" } }, "required": ["sentiment", "summary"]}Gunakan pola ini untuk moderasi, triage tiket, atau kategorisasi pesan. Enum membatasi jawaban pada nilai yang kamu kontrol, sehingga proses hilir tidak perlu menangani kombinasi liar.
3. Struktur rekursif untuk data bertingkat
Schema boleh referensi dirinya sendiri lewat $ref. Contoh: bagan organisasi dengan manajer dan anak laporan, atau pohon komentar dengan balasan. Gemini mengikuti referensi ini dan menghasilkan struktur yang konsisten dengan kedalaman yang diminta model.
Validasi di sisi klien
Output dari Gemini sudah dijamin JSON valid secara sintaksis, tetapi kamu tetap harus memvalidasi nilai-nilainya. Dokumentasi resmi menekankan bahwa “structured output guarantees syntactically correct JSON, but does not guarantee the values are semantically correct.”
Cara paling aman adalah dengan library seperti Pydantic (Python) atau Zod (TypeScript). Setelah parse JSON, langsung panggil validator. Jika gagal, tampilkan pesan ramah ke pengguna dan minta model mencoba lagi dengan prompt yang lebih ketat. Jangan diam-diam menerima nilai yang tidak lolos validasi. ✅
# Python (Pydantic)from pydantic import BaseModel, Fieldfrom google import genaiclass Recipe(BaseModel): recipe_name: str ingredients: list[str] prep_time_minutes: int | None = Noneclient = genai.Client()interaction = client.interactions.create( model="gemini-3.8-flash", input="Ekstrak data dari teks: '...' ", response_format={ "type": "text", "mime_type": "application/json", "schema": Recipe.model_json_schema(), },)recipe = Recipe.model_validate_json(interaction.output_text)Pola serupa berlaku di TypeScript dengan z.fromJSONSchema() dan schema.parse(JSON.parse(interaction.output_text)).
Tips dan jebakan umum
- Mulai dari schema, bukan dari prompt. Tulis struktur yang kamu butuhkan lebih dulu, baru rancang prompt yang mengarah ke struktur itu. Ini mencegah kamu menulis prompt panjang tanpa tujuan.
- Beri deskripsi pada setiap properti. Field
descriptiondi JSON Schema sangat membantu model memahami makna. Misalnya,prep_time_minuteslebih jelas jika ada deskripsi “waktu persiapan dalam menit”. - Gunakan enum untuk pilihan terbatas. Daripada mengandalkan frasa “jawab hanya dengan ya/tidak”, tulis
enum: ["yes", "no"]. - Batasi panjang jika perlu. Untuk ringkasan, tambahkan
maxLengthdi schema sehingga model tidak menghasilkan paragraf panjang. - Tangani kasus kosong. Jika input bisa menghasilkan array kosong atau field null, deklarasikan
nulldi tipe:{"type": ["string", "null"]}. - Jangan percaya satu percobaan. Jalankan beberapa prompt uji dan cek distribusi nilai. JSON terstruktur bukan jaminan akurasi fakta. 🚨
Kapan perlu function calling?
Structured output cocok untuk mengisi form, klasifikasi, atau menghasilkan data yang langsung dipakai aplikasi. Function calling lebih tepat ketika model perlu memicu aksi—misalnya mengirim email, menulis ke database, atau memanggil API internal. Pada Gemini 3, keduanya dapat digabung: schema JSON untuk format akhir, function call untuk langkah di tengah percakapan.
Untuk pemula, mulai dari structured output dulu. Setelah alur data stabil, tambahkan function call hanya jika memang ada aksi yang harus dijalankan. Mencampur keduanya di awal sering membuat alur sulit di-debug. 🤖
Kesimpulan dan latihan
Prompt AI JSON terstruktur lewat Gemini API memberi cara yang jauh lebih andal untuk menghubungkan model bahasa dengan aplikasi. Kuncinya: tentukan schema lebih dulu, gunakan response_format dengan mime_type application/json, lalu validasi hasilnya di sisi klien dengan Pydantic, Zod, atau validator JSON Schema pilihanmu.
Latihan kecil yang bisa kamu coba sekarang: buat schema untuk pesan pelanggan (sentiment enum, ringkasan singkat, dan daftar tag), lalu minta model mengklasifikasikan lima pesan berbeda. Cek apakah semua output lolos parsing dan apakah distribusinya masuk akal. Dari situ, kamu bisa berkembang ke kasus yang lebih kompleks. 🚀
Sumber dan kredit
Sumber primer: Structured outputs — Gemini API dan Interactions API dari Google AI for Developers, diakses 14 September 2026. Pendukung: Prompt design strategies. Kredit visual: diagram alur Kuskuskuy original (PIL), tanpa aset pihak ketiga.
