Keluaran terstruktur dengan API yang kompatibel dengan OpenAI: panduan JSON Schema

Structured Outputs memungkinkan aplikasi meminta JSON yang mengikuti skema tertentu, bukan sekadar menyuruh model “mengembalikan JSON”. Pada API yang kompatibel dengan OpenAI, JSON Schema yang sama dapat dipakai melalui Responses atau Chat Completions, tetapi format pembungkusnya berbeda dan dukungannya harus diverifikasi pada model serta rute yang sebenarnya.

Pola produksi yang aman memiliki tiga lapisan: gunakan strict jika didukung, uraikan dan validasi ulang JSON di aplikasi, lalu terapkan aturan bisnis deterministik. Kepatuhan terhadap skema mengurangi kegagalan format, tetapi tidak membuktikan kebenaran faktual atau semantik.

Structured Outputs berbeda dari mode JSON

Metode	JSON valid	Memaksa skema	Penggunaan umum
Instruksi saja	Tidak dijamin	Tidak	Prototipe yang menerima kegagalan penguraian
Mode JSON	Ya jika didukung dan generasi selesai	Tidak	JSON fleksibel yang divalidasi aplikasi
Structured Outputs dengan strict: true	Ya, dengan penanganan penyelesaian dan penolakan	Ya dalam cakupan yang didukung	Ekstraksi bertipe dan alur kerja aplikasi

Panduan OpenAI Structured Outputs merekomendasikannya dibanding mode JSON ketika model dan endpoint mendukung. Format respons terstruktur menghasilkan objek data yang dapat diprediksi; Function Calling meminta aplikasi melakukan tindakan. Skemanya dapat serupa, tetapi ID panggilan dan pesan hasil mengikuti kontrak yang berbeda.

Definisikan skema sebelum memilih endpoint

Alur kerja triase dukungan membutuhkan empat bidang:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "requires_human": {
      "type": "boolean"
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["category", "priority", "requires_human", "summary"],
  "additionalProperties": false
}

Menjadikan semua properti wajib dan menetapkan additionalProperties: false menghasilkan objek yang stabil. Namun, tidak semua kata kunci JSON Schema dapat dipindahkan antarpenyedia. OpenAI mendokumentasikan cakupan tertentu; penyedia lain dapat mendukung cakupan yang berbeda atau tidak menyediakan mode skema ketat.

Kirim skema dengan Responses API

Responses menempatkan skema di text.format:

export MODELFLARE_API_KEY="<YOUR_API_KEY>"
export MODEL_ID="<MODEL_WITH_VERIFIED_STRUCTURED_OUTPUT_SUPPORT>"

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL_ID\",
    \"input\": \"Pelanggan ditagih dua kali dan meminta pengembalian dana.\",
    \"text\": {
      \"format\": {
        \"type\": \"json_schema\",
        \"name\": \"support_ticket\",
        \"schema\": {
          \"type\": \"object\",
          \"properties\": {
            \"category\": {
              \"type\": \"string\",
              \"enum\": [\"billing\", \"technical\", \"account\"]
            },
            \"priority\": {
              \"type\": \"integer\",
              \"minimum\": 1,
              \"maximum\": 3
            },
            \"requires_human\": { \"type\": \"boolean\" },
            \"summary\": { \"type\": \"string\" }
          },
          \"required\": [\"category\", \"priority\", \"requires_human\", \"summary\"],
          \"additionalProperties\": false
        },
        \"strict\": true
      }
    }
  }"

Kirim ke POST https://modelflare.dev/v1/responses dengan Authorization: Bearer <YOUR_API_KEY>. Konten berada dalam item keluaran bertipe. SDK dapat menyediakan fungsi bantu, tetapi klien HTTP tetap harus menemukan teks keluaran yang sudah selesai dan menguraikannya sebagai JSON secara eksplisit.

Kirim skema yang sama dengan Chat Completions

Chat Completions memakai response_format.json_schema:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL_ID\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"Pelanggan ditagih dua kali dan meminta pengembalian dana.\"
      }
    ],
    \"response_format\": {
      \"type\": \"json_schema\",
      \"json_schema\": {
        \"name\": \"support_ticket\",
        \"schema\": {
          \"type\": \"object\",
          \"properties\": {
            \"category\": {
              \"type\": \"string\",
              \"enum\": [\"billing\", \"technical\", \"account\"]
            },
            \"priority\": {
              \"type\": \"integer\",
              \"minimum\": 1,
              \"maximum\": 3
            },
            \"requires_human\": { \"type\": \"boolean\" },
            \"summary\": { \"type\": \"string\" }
          },
          \"required\": [\"category\", \"priority\", \"requires_human\", \"summary\"],
          \"additionalProperties\": false
        },
        \"strict\": true
      }
    }
  }"

JSON biasanya berupa string di choices[0].message.content dan perlu diuraikan.

Tujuan	Responses API	Chat Completions
Wadah skema	text.format	response_format.json_schema
Jenis format	text.format.type	response_format.type
Nama skema	text.format.name	response_format.json_schema.name
Isi skema	text.format.schema	response_format.json_schema.schema
Mode ketat	text.format.strict	response_format.json_schema.strict
Hasil	Item keluaran / fungsi bantu SDK	choices[0].message.content

Lapisan kompatibilitas Modelflare mengonversi kedua format pembungkus pada rute OpenAI/Codex yang didukung, tetapi tidak dapat menciptakan Structured Outputs pada model penyedia yang tidak mendukungnya. Untuk Chat Completions yang diteruskan tanpa transformasi, kontrak penyedia tetap menjadi sumber acuan.

Validasi struktur dan makna secara terpisah

{
  "category": "billing",
  "priority": 2,
  "requires_human": true,
  "summary": "Pelanggan melaporkan tagihan ganda dan meminta pengembalian dana."
}

Validasi struktural

Validator JSON Schema memeriksa properti wajib, properti tak terduga, jenis data, enumerasi, dan rentang nilai. Walaupun penyedia menjanjikan kepatuhan ketat, validasi aplikasi tetap melindungi dari rute yang tidak didukung, kesalahan integrasi, keluaran terpotong, dan perubahan kontrak.

Validasi semantik dan bisnis

Skema tidak mengetahui apakah tagihan ganda benar-benar terjadi, apakah priority: 2 tepat, atau siapa yang boleh menyetujui pengembalian dana. Perlakukan objek sebagai klasifikasi usulan, bandingkan dengan data tepercaya, lalu terapkan izin dan batas keuangan dalam kode deterministik. JSON yang valid tidak boleh melewati otorisasi, pencatatan biaya, atau batas keamanan.

Tangani keluaran tidak lengkap dan pengecualian

Penolakan

Periksa status respons dan bentuk penolakan sebelum mencari JSON. Penolakan karena alasan keamanan bukan kesalahan penguraian.

Keluaran terpotong dan batas keluaran

Jika pembuatan respons berhenti sebelum objek ditutup, skema tidak dapat memulihkan bagian yang hilang. Periksa status penyelesaian dan alasan berhenti, lalu tetapkan batas keluaran yang cukup tetapi tetap terbatas.

Kata kunci yang tidak didukung

Mulailah dari objek, larik, jenis primitif, enumerasi, properti wajib, dan properti tambahan yang dinyatakan secara eksplisit. Periksa dokumentasi sebelum memakai referensi, rekursi, union kompleks, atau validasi lanjutan.

Latensi saat skema pertama kali digunakan

Sebagian penyedia memproses awal dan menyimpan skema baru di cache. Gunakan kembali skema yang stabil dan berversi, serta pisahkan pengukuran penggunaan pertama dari kondisi stabil.

Model atau rute tidak kompatibel

Endpoint dapat menerima Chat Completions biasa tetapi menolak json_schema atau mengabaikan strict. Respons 200 yang berisi JSON bukan bukti kepatuhan ketat. Sertakan masukan tidak valid dan kasus batas dalam pengujian.

Jalankan matriks kompatibilitas

Pengujian	Bukti yang disimpan
Objek wajib minimal	Status, model, rute, objek terurai, hasil validasi
Semua nilai enumerasi	Pembuatan dan penguraian setiap nilai
Informasi hilang	Nilai pengganti terbatas atau permintaan klarifikasi
Masukan terkait keamanan	Format penolakan dan penanganan aplikasi
Batas keluaran rendah	Status penyelesaian dan penanganan keluaran terpotong
Fitur tak didukung	Kesalahan eksplisit atau batasan yang diabaikan
Pembungkus Responses dan Chat	Objek aplikasi yang setara
Pengulangan skema stabil	Penggunaan pertama dibanding kondisi stabil

Pertahankan skema, instruksi, wilayah, mode streaming, dan batas keluaran yang sama, lalu catat tanggal pengujian.

Pilih endpoint setelah menguji alur kerja

Gunakan Responses untuk item keluaran bertipe, peristiwa streaming, atau alur kerja alat yang lebih luas. Gunakan Chat Completions untuk integrasi berbasis pesan jika rutenya mendukung response_format. Lihat Responses API dan Chat Completions.

Apa pun endpoint-nya:

1. simpan satu sumber acuan JSON Schema yang berversi;
2. ubah pembungkus tanpa mengubah makna;
3. validasi respons yang sudah selesai;
4. terapkan aturan bisnis deterministik setelah validasi struktur;
5. pantau kegagalan penguraian, penolakan, keluaran terpotong, dan kompatibilitas secara terpisah.

Mulai migrasi dengan Panduan API yang Kompatibel dengan OpenAI, dan gunakan Panduan Streaming AI API untuk aliran yang tidak lengkap. Periksa Model & Harga, lalu uji Structured Outputs pada rute yang benar-benar digunakan oleh kunci API.

Structured Outputs membatasi respons model menjadi antarmuka aplikasi yang lebih andal. Namun, fitur ini tidak menggantikan verifikasi fakta, otorisasi, atau logika pencatatan biaya. Klaim “kompatibel dengan OpenAI” tetap harus diuji per fitur.