Pernah minta AI API buat “jawab dalam JSON” lalu hasilnya malah berantakan? Kadang diawali kalimat “Tentu, berikut datanya:”, kadang field-nya berubah nama sendiri, kadang kurang kurung tutup. Script kamu langsung error, pipeline macet, dan kamu mengutuk si AI sambil memperbaiki parser.

Masalah ini punya solusi resmi di 2026: structured output. Fitur ini bikin API AI mengembalikan data yang dijamin sesuai skema JSON yang kamu definisikan — bukan sekadar “diharapkan”. Artinya: tidak lagi perlu parser defensif, tidak lagi try-catch tiga lapis. Ini skill fundamental kalau kamu mau serius bikin otomatisasi data dengan API AI.

Artikel ini bahas konsepnya, contoh kodenya, dan use case bisnis nyata. Cocok buat kamu yang sudah paham dasar cara pakai API key AI dan ingin naik level.

Masalah dengan “Tolong Jawab dalam JSON”

Cara naif begini:

prompt = """
Ekstrak data pembelian ini: 'Budi beli 2 mouse Logitech Rp150.000, dikirim ke Bandung'
Balas dalam JSON dengan field: nama, barang, qty, harga, kota.
"""

Model biasanya menjawab benar. Tapi “biasanya” itu musuh terbesar otomatisasi. Secara statistik, kamu akan ketemu:

  1. Jawaban ditambah teks pengantar — "Berikut JSON-nya:" di awal, atau catatan di akhir.
  2. Markdown fence — JSON dibungkus json ....
  3. Field tidak konsisten — sekali qty, sekali quantity, sekali jumlah.
  4. Tipe data berubah — harga kadang "Rp150.000" (string) kadang 150000 (angka).
  5. Halusinasi field tambahan — model menambahkan total_harga yang tidak kamu minta.

Untuk demo dan script sekali pakai, itu mengganggu. Untuk pipeline produksi yang jalan tiap hari dengan ratusan dokumen? Itu bencana.

Solusinya: Structured Output

Structured output memindahkan kontrak format dari prompt (yang bersifat permintaan) ke API (yang bersifat pemaksaan). Kamu mendefinisikan skema JSON, dan API memaksa model hanya bisa menghasilkan output yang lolos validasi skema itu.

Analoginya: prompt itu kayak minta tolong ke teman (“tolong ya datanya rapi”), structured output itu kayak form digital yang gak bisa di-submit kalau field salah format.

Berikut contoh pemakaian dengan format OpenAI-compatible (format yang juga dipakai banyak provider lain, termasuk API OpenAI-compatible di Indonesia):

from openai import OpenAI
import json

client = OpenAI(api_key="API_KEY_KAMU", base_url="https://api-provider-kamu.com/v1")

schema = {
    "type": "object",
    "properties": {
        "nama": {"type": "string"},
        "barang": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "nama_barang": {"type": "string"},
                    "qty": {"type": "integer"},
                    "harga": {"type": "number"}
                },
                "required": ["nama_barang", "qty", "harga"]
            }
        },
        "kota_tujuan": {"type": "string"}
    },
    "required": ["nama", "barang", "kota_tujuan"]
}

response = client.chat.completions.create(
    model="model-pilihan-kamu",
    messages=[
        {"role": "system", "content": "Ekstrak data pembelian dari teks user. Output JSON sesuai skema."},
        {"role": "user", "content": "Budi beli 2 mouse Logitech Rp150.000, dikirim ke Bandung"}
    ],
    response_format={"type": "json_schema", "json_schema": {"name": "pembelian", "schema": schema}}
)

data = json.loads(response.choices[0].message.content)
print(data["barang"][0]["nama_barang"])  # dijamin ada, dijamin string

Perhatikan: tidak ada parser defensif, tidak ada regex pembersih markdown, tidak ada cek if "qty" in data. Skema sudah menjamin semua itu. Kalau data sumbernya tidak menyebutkan qty, field tetap keluar (kosong atau null sesuai desainmu), bukan hilang diam-diam.

Untuk provider seperti Anthropic, mekanismenya lewat tool use — kamu definisikan “tool” yang parameternya adalah skema JSON-mu, dan model memanggil tool itu dengan data terstruktur. Hasil akhirnya sama: JSON terjamin valid.

Tips Desain Skema yang Bagus

  1. Pisahkan string bebas dari enum. Kalau kategorinya pasti (status hanya bisa “baru”/”proses”/”selesai”), pakai enum di skema. Model tidak bisa berimprovisasi.
  2. Baksa tipe data sejak awal. Harga sebagai number, tanggal dalam format "format": "date" — jangan biarkan model mengembalikan “Rp150.000” sebagai string lalu kamu bersihin belakangan.
  3. Pakai array untuk list, bukan string yang digabung koma. "tags": ["murah", "laris"] jauh lebih enak diolah daripada "tags": "murah, laris".
  4. Deskripsikan tiap field. Banyak provider mendukung properti description di skema. Satu kalimat deskripsi per field meningkatkan akurasi ekstraksi secara signifikan.
  5. Model kecil cukup untuk ekstraksi sederhana. Tugas “ubah teks jadi JSON sesuai skema” itu ringan — jangan buang model paling mahal untuk ini. Ini juga salah satu tips hemat kuota token API yang paling gampang diterapkan.

Use Case Bisnis Nyata

  • Ekstraksi order dari chat WhatsApp/DM. Pesanan pelanggan masuk dalam bahasa bebas (“kak mau order yang besar 2, yang kecil 1, kirim ke rumah ya”), output-nya baris database yang siap masuk sistem. Kombinasikan dengan pola auto-reply WhatsApp dengan API AI untuk pipeline order penuh.
  • Digitalisasi dokumen. Faktur, kuitansi, form supplier yang difoto — masuk sebagai input (teks atau gambar untuk model multimodal), keluar sebagai JSON inventori. Pola lengkapnya pernah kami bahas di ekstraksi data faktur dengan AI OCR.
  • Klasifikasi otomatis tiket CS. Setiap keluhan masuk diklasifikasi (kategori, urgensi, sentimen) lewat enum yang dijamin konsisten, langsung dirutekan ke tim yang tepat.
  • Monitoring harga kompetitor. Hasil scrape dikonversi jadi data terstruktur sebelum masuk spreadsheet — tanpa perlu berantakan dengan format HTML mentah.

Jangan Lupakan Keamanan

Kalau pipeline ini jalan di server, ingat dua hal: simpan API key di environment variable (jangan hardcode seperti contoh di atas — itu hanya ilustrasi), dan validasi data hasil ekstraksi tetap di sisi aplikasi untuk hal-hal kritis seperti angka harga. AI menjamin format, bukan kebenaran isi. Untuk pengamanan key secara menyeluruh, baca cara mengamankan API key AI.

Kesimpulan

Structured output mengubah API AI dari “teman yang jawabnya kadang berantakan” jadi “komponen software yang bisa diandalkan”. Kalau kamu sedang membangun otomatisasi apa pun yang melibatkan bahasa manusia di satu sisi dan database di sisi lain, ini fitur pertama yang harus kamu kuasai. Mulai dari satu use case kecil — misalnya ekstraksi order chat jadi JSON — lalu rasakan bedanya pipeline yang tidak lagi butuh parser penyelamat.