Panduan inti
Structured Outputs & Tool Calling
Kembalikan JSON atau biarkan model memanggil fungsi di aplikasi Anda
Structured output meminta JSON dari model. Tool calling memungkinkan model untuk meminta fungsi yang dieksekusi oleh aplikasi Anda. Bidang yang tersedia bergantung pada format API dan model, jadi gunakan satu format yang konsisten di sepanjang percakapan dan validasi setiap nilai yang dihasilkan model di aplikasi Anda.
Pilih format API
| Kebutuhan | API | Bidang |
|---|---|---|
| Respons objek JSON portabel | /v1/chat/completions | response_format: {"type": "json_object"} |
| Pemanggilan fungsi yang kompatibel dengan OpenAI | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| Alat Respons OpenAI | /v1/responses | Bidang tools, tool_choice, dan text pada Respons |
| Penggunaan alat atau pemikiran native Claude | /v1/messages | Skema alat Anthropic Messages |
| Deklarasi fungsi atau alat bawaan Gemini | /v1beta/models/:model:generateContent | tools dan bagian konten native Gemini |
Gunakan alat bawaan hanya dengan format API yang mendokumentasikannya; TokenLab tidak mengonversi alat tersebut antar format.
Mode JSON
Untuk objek JSON yang berfungsi di berbagai model chat, gunakan mode JSON Chat Completions:
{
"model": "gpt-5.6-terra",
"messages": [
{
"role": "user",
"content": "Return a JSON object with city and weather."
}
],
"response_format": { "type": "json_object" }
}Model yang mendukung mode JSON mencantumkan json-mode dalam capabilities di GET /v1/models. Chat Completions menerima text dan json_object. json_schema dan strict bersifat spesifik untuk model dan format; gunakan hanya jika model yang dipilih mendokumentasikan dukungannya.
Selalu lakukan parsing dan validasi JSON yang dikembalikan di server Anda. Mode JSON tidak menggantikan validasi skema di tingkat aplikasi.
Menyelesaikan tool call
TokenLab mengembalikan nama fungsi dan argumen; aplikasi Anda yang mengeksekusinya:
- Kirim pesan beserta definisi alat (tool definitions).
- Baca respons model untuk
tool_calls,function_call,tool_useAnthropic, atau bagian pemanggilan fungsi Gemini. - Eksekusi alat di backend Anda sendiri.
- Lampirkan hasil alat dalam format API yang sama.
- Lanjutkan percakapan hingga model memberikan jawaban akhir.
Gunakan format API yang sama hingga tool call dan jawaban akhir selesai. Keempat format tersebut merepresentasikan status alat dengan cara yang berbeda.
Contoh Chat Completions
curl https://api.tokenlab.sh/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"messages": [
{
"role": "user",
"content": "Extract name and email as JSON. If needed, look up the customer."
}
],
"response_format": { "type": "json_object" },
"tools": [
{
"type": "function",
"function": {
"name": "lookup_customer",
"description": "Look up a customer by email",
"parameters": {
"type": "object",
"properties": {
"email": { "type": "string" }
},
"required": ["email"]
}
}
}
]
}'Menulis skema yang berguna
- Buat skema yang ringkas dan eksplisit. Skema bersarang yang besar menambah token dan mengurangi keandalan.
- Utamakan bidang wajib (required fields) untuk nilai yang tanpanya produk Anda tidak dapat berjalan.
- Gunakan enum untuk kumpulan nilai tertutup yang bergantung pada UI atau backend Anda.
- Sertakan contoh dalam prompt jika model kesulitan dengan bentuk skema.
- Jika suatu bidang tidak didukung, hapus bidang tersebut atau gunakan format API yang mendokumentasikannya.
Sebelum mengeksekusi alat
- Catat format API, model, nama alat, dan nama bidang skema.
- Validasi argumen alat sebelum mengeksekusi efek samping apa pun.
- Terapkan pemeriksaan izin Anda sendiri sebelum eksekusi alat.
- Buat eksekusi alat menjadi idempoten jika percobaan ulang (retry) klien dapat mengulangi pemanggilan alat yang sama.
- Jangan mencatat rahasia yang dikembalikan oleh alat ke dalam pesan yang dapat dilihat model.
Referensi API
| Topik | Referensi |
|---|---|
| API Multi-Format | Multi-Format API |
| Membuat Chat Completion | Buat Chat Completion |
| Membuat Respons | Buat Respons |
| Membuat Pesan | Create Message |
| Menghasilkan Konten Gemini | Generate Gemini Content |