Keluaran terstruktur

Structured outputs membuat model membalas dengan JSON alih-alih prosa, baik berupa objek JSON yang valid maupun JSON yang mengikuti skema yang Anda berikan. Ini adalah cara yang andal untuk mengekstrak field, mengklasifikasikan teks, atau meneruskan balasan langsung ke kode.

Gunakan model dengan capabilities.json_mode berupa true di daftar model.

JSON skema

const completion = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    { role: "system", content: "Extract the event details." },
    { role: "user", content: "Team offsite on March 3rd at the Lisbon office, 10am." },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "event",
      strict: true,
      schema: {
        type: "object",
        properties: {
          title: { type: "string" },
          date: { type: "string" },
          location: { type: "string" },
        },
        required: ["title", "date", "location"],
        additionalProperties: false,
      },
    },
  },
});

const event = JSON.parse(completion.choices[0].message.content);

Dengan strict: true, model yang mendukung skema ketat hanya menghasilkan output yang lolos validasi. Strict mode mendukung subset dari JSON Schema: atur additionalProperties: false pada setiap objek dan cantumkan setiap properti dalam required (gunakan union dengan null untuk nilai opsional).

JSON Mode

Untuk JSON yang valid tanpa skema tetap, gunakan json_object. Sebutkan di prompt bahwa Anda menginginkan JSON dan jelaskan bentuknya, karena model tidak punya informasi lain untuk dijadikan acuan:

{
  "model": "gemini-3.6-flash",
  "response_format": { "type": "json_object" },
  "messages": [
    { "role": "user", "content": "List three primary colours as JSON: {\"colours\": [...]}" }
  ]
}

Tentang Responses API

Skema diletakkan di bawah text.format:

{
  "model": "gpt-5.5",
  "input": "Team offsite on March 3rd at the Lisbon office, 10am.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "event",
      "strict": true,
      "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"], "additionalProperties": false }
    }
  }
}

Helper SDK untuk structured outputs (client.chat.completions.parse dengan Zod atau Pydantic, client.responses.parse) mengirim field yang sama dan berfungsi tanpa perubahan.

Hal yang perlu diperiksa

• Model yang tidak mendukung schema mengembalikan 400 alih-alih diam-diam mengabaikannya. Pilih model lain atau beralih ke mode JSON.
• Balasan yang terpotong oleh max_tokens (finish_reason: "length") adalah JSON yang tidak lengkap. Sisakan ruang dalam batasnya.
• Model tetap bisa menolak permintaan; periksa penolakan sebelum mem-parse.
• Tetap validasi objek hasil parse. Schema menjamin bentuk, bukan kebenaran.
• Di endpoint Messages, yang tidak punya response_format, pola yang biasa dipakai adalah satu tool dengan input_schema berupa schema Anda, dan tool_choice yang memaksanya.