Lewati ke konten
kenari.

Output terstruktur

Output terstruktur berarti model menjawab dengan JSON yang bisa langsung di-parse kodemu, bukan teks bebas. Ketiga API chat mendukungnya: response_format di Chat completions, text.format di Responses, dan output_config.format di Messages. kenari meminta JSON kepada setiap model, tetapi tidak memeriksa hasilnya, jadi validasi setiap balasan di kodemu sendiri.

{"type": "json_object"} meminta satu objek JSON yang valid. kenari juga menambahkan instruksi untuk menjawab dengan JSON ke system prompt, jadi kamu tidak perlu menulisnya sendiri.

Terminal window
curl https://kenari.id/v1/chat/completions \
-H "Authorization: Bearer $KENARI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "step-3-7-flash:free",
"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Balas dengan satu objek JSON saja."},
{"role": "user", "content": "Ambil vendor dan total: Faktur dari Toko Maju, total 417000 rupiah."}
]
}'

{"type": "json_schema"} meminta JSON yang sesuai dengan sebuah JSON Schema. Beri skema itu name, dan taruh skemanya di schema.

{
"model": "step-3-7-flash:free",
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "invoice",
"schema": {
"type": "object",
"properties": {
"vendor": {"type": "string"},
"total": {"type": "integer"}
},
"required": ["vendor", "total"]
}
}
},
"messages": [
{"role": "user", "content": "Ambil field faktur ini: Faktur dari Toko Maju, total 417000 rupiah."}
]
}

Di Responses, taruh format di text.format. Field skema langsung berada di objek format itu, bukan di bawah json_schema:

{
"model": "step-3-7-flash:free",
"input": "Ambil field invoice: Invoice dari Toko Maju, total 417000 rupiah.",
"text": {
"format": {
"type": "json_schema",
"name": "invoice",
"schema": {
"type": "object",
"properties": {
"vendor": {"type": "string"},
"total": {"type": "integer"}
},
"required": ["vendor", "total"]
}
}
}
}

{"type": "json_object"} juga bisa dipakai di sana. Response mengembalikan format yang kamu minta di field text, dan tipe text.format lainnya mengembalikan 400.

Di Messages, taruh skema di output_config.format. Field lama output_format di level teratas juga diterima dengan arti yang sama.

{
"model": "step-3-7-flash:free",
"max_tokens": 1024,
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"vendor": {"type": "string"},
"total": {"type": "integer"}
},
"required": ["vendor", "total"],
"additionalProperties": false
}
}
},
"messages": [
{"role": "user", "content": "Ambil field invoice: Invoice dari Toko Maju, total 417000 rupiah."}
]
}

Di ketiga API, kenari melakukan dua hal untuk request output terstruktur:

  • kenari menambahkan instruksi singkat ke system prompt yang meminta JSON, beserta skemamu bila kamu mengirimnya. Setiap model menerimanya, jadi model menjawab dengan JSON meskipun provider-nya mengabaikan format. Instruksi ini ditagih sebagai token input, sama seperti bagian prompt lainnya.
  • kenari meneruskan format lewat field milik provider itu sendiri bila provider tersebut diketahui menerimanya. Di sana provider bisa menegakkan skema. Di provider lain, model hanya mengikuti instruksi.

GET /v1/models tidak menyebutkan model mana yang menegakkan skema, dan hal itu bisa berubah, jadi rencanakan validasi dan coba lagi di setiap model. Jika provider menolak format, kamu bisa mendapat 400. Balasan tetap bisa berupa JSON tidak valid, atau JSON yang dibungkus code fence.

Minta JSON, validasi balasan terhadap skema-mu, dan kirim error validasinya kembali jika gagal. Pola ini dapat digunakan di semua model.

import os
from openai import OpenAI
from pydantic import BaseModel, ValidationError
class Invoice(BaseModel):
vendor: str
total: int
client = OpenAI(
base_url="https://kenari.id/v1",
api_key=os.environ["KENARI_API_KEY"],
)
def extract_invoice(text: str, attempts: int = 3) -> Invoice:
messages = [
{"role": "system", "content": "Balas dengan satu objek JSON saja."},
{"role": "user", "content": f"Ambil vendor dan total dari: {text}"},
]
for _ in range(attempts):
response = client.chat.completions.create(
model="step-3-7-flash:free",
messages=messages,
response_format={
"type": "json_schema",
"json_schema": {"name": "invoice", "schema": Invoice.model_json_schema()},
},
)
reply = response.choices[0].message.content or ""
try:
return Invoice.model_validate_json(reply)
except ValidationError as error:
messages += [
{"role": "assistant", "content": reply},
{"role": "user", "content": f"Balasan itu tidak valid: {error}. Balas hanya dengan JSON yang sudah diperbaiki."},
]
raise RuntimeError("tidak ada JSON valid setelah beberapa percobaan")
print(extract_invoice("Faktur dari Toko Maju, total 417000 rupiah."))

Meminta format tidak menambah biaya tersendiri. Instruksi yang ditambahkan kenari ditagih sebagai token input. Setiap percobaan ulang adalah request baru, yang ditagih seperti biasa di model berbayar.

Memaksa panggilan tool meminta argumen yang berbentuk sesuai skema, dan dapat digunakan di model apa pun dengan tool_call bernilai true. Definisikan satu tool yang input_schema-nya adalah skema-mu, paksa dengan tool_choice, lalu baca argumennya dari panggilan itu. Di Messages:

import os
import anthropic
client = anthropic.Anthropic(
base_url="https://kenari.id",
api_key=os.environ["KENARI_API_KEY"],
)
response = client.messages.create(
model="step-3-7-flash:free",
max_tokens=1024,
tools=[
{
"name": "record_invoice",
"description": "Catat field sebuah faktur.",
"input_schema": {
"type": "object",
"properties": {
"vendor": {"type": "string"},
"total": {"type": "integer"},
},
"required": ["vendor", "total"],
},
}
],
tool_choice={"type": "tool", "name": "record_invoice"},
messages=[{"role": "user", "content": "Faktur dari Toko Maju, total 417000 rupiah."}],
)
invoice = next(block.input for block in response.content if block.type == "tool_use")
print(invoice)

block.input sudah berupa objek. Kamu tidak perlu menjalankan tool atau mengirim hasilnya kembali. Pola yang sama berlaku di Chat completions dengan function tool dan tool_choice: {"type": "function", "function": {"name": "record_invoice"}}, dengan JSON-nya ada di tool_calls[0].function.arguments. Tetap validasi, dan tangani balasan yang tidak memuat panggilan tool. Lihat Function calling.

  • Balasan yang terpotong oleh max_tokens adalah JSON yang tidak valid. Di Chat completions, pastikan finish_reason bukan length. Di Responses, pastikan status bukan incomplete. Di Messages, pastikan stop_reason bukan max_tokens. Model reasoning memakai sebagian max_tokens untuk berpikir, jadi sisakan ruang. Lihat Penalaran.
  • Jangan mengandalkan aturan skema seperti minimum atau pattern ditegakkan. Model berbeda-beda, jadi periksa di kodemu sendiri.