Temel kılavuzlar
Yapılandırılmış Çıktılar ve Araç Çağırma
JSON döndürün veya bir modelin uygulamanızdaki fonksiyonları çağırmasına izin verin
Yapılandırılmış çıktı, bir modelden JSON talep eder. Araç çağırma (tool calling) ise modelin, uygulamanızın yürüteceği bir fonksiyonu talep etmesini sağlar. Kullanılabilir alanlar API formatına ve modele bağlıdır, bu nedenle konuşma boyunca tek bir format kullanın ve model tarafından üretilen her değeri uygulamanızda doğrulayın.
Bir API formatı seçin
| İhtiyaç | API | Alanlar |
|---|---|---|
| Taşınabilir JSON nesnesi yanıtları | /v1/chat/completions | response_format: {"type": "json_object"} |
| OpenAI uyumlu fonksiyon çağırma | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| OpenAI Yanıt araçları | /v1/responses | Yanıtlar tools, tool_choice ve text alanları |
| Claude'a özgü araç kullanımı veya düşünme | /v1/messages | Anthropic Messages araç şeması |
| Gemini fonksiyon bildirimleri veya yerleşik araçlar | /v1beta/models/:model:generateContent | Gemini'ye özgü tools ve içerik parçaları |
Yerleşik araçları yalnızca onları belgeleyen API formatı ile kullanın; TokenLab bu araçları formatlar arasında dönüştürmez.
JSON Modu
Birçok sohbet modelinde çalışan bir JSON nesnesi için Chat Completions JSON modunu kullanın:
{
"model": "gpt-5.6-terra",
"messages": [
{
"role": "user",
"content": "Return a JSON object with city and weather."
}
],
"response_format": { "type": "json_object" }
}JSON modunu destekleyen modeller, GET /v1/models içindeki capabilities kısmında json-mode listeler. Chat Completions text ve json_object değerlerini kabul eder. json_schema ve strict modele ve formata özeldir; bunları yalnızca seçilen modelin desteği belgelendiğinde kullanın.
Döndürülen JSON'ı sunucunuzda her zaman ayrıştırın ve doğrulayın. JSON modu, uygulama düzeyindeki şema doğrulamasının yerini tutmaz.
Bir araç çağrısını tamamlama
TokenLab fonksiyon adını ve argümanlarını döndürür; uygulamanız bunu yürütür:
- Mesajları ve araç tanımlarını gönderin.
- Model yanıtını
tool_calls,function_call, Anthropictool_useveya Gemini fonksiyon çağrısı parçaları için okuyun. - Aracı kendi arka ucunuzda (backend) yürütün.
- Araç sonucunu aynı API formatında ekleyin.
- Model nihai bir yanıt döndürene kadar konuşmaya devam edin.
Araç çağrısı ve nihai yanıt tamamlanana kadar aynı API formatını koruyun. Dört format, araç durumunu farklı şekillerde temsil eder.
Chat Completions Örneği
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"]
}
}
}
]
}'Faydalı bir şema yazın
- Şemaları küçük ve açık tutun. Büyük iç içe geçmiş şemalar token ekler ve güvenilirliği azaltır.
- Ürününüzün onsuz devam edemeyeceği değerler için gerekli (required) alanları tercih edin.
- Arayüzünüzün veya arka ucunuzun bağlı olduğu kapalı kümeler için enum'lar kullanın.
- Model bir şekli oluşturmakta zorlandığında isteme (prompt) örnekler ekleyin.
- Bir alan desteklenmiyorsa, onu kaldırın veya belgeleyen bir API formatı kullanın.
Bir aracı yürütmeden önce
- API formatını, modeli, araç adlarını ve şema alanı adlarını kaydedin.
- Herhangi bir yan etkiyi yürütmeden önce araç argümanlarını doğrulayın.
- Araç yürütmeden önce kendi izin kontrollerinizi uygulayın.
- Bir istemci yeniden denemesi aynı araç çağrısını tekrarlayabildiğinde, araç yürütmeyi idempotent (eşgüçlü) hale getirin.
- Araçlar tarafından döndürülen gizli bilgileri modelin görebileceği mesajlara kaydetmeyin.
API Referansı
| Konu | Referans |
|---|---|
| Çoklu Format API | Çoklu Format API |
| Sohbet Tamamlama Oluştur | Sohbet Tamamlama Oluştur |
| Yanıt Oluştur | Yanıt Oluştur |
| Mesaj Oluştur | Mesaj Oluştur |
| Gemini İçeriği Oluştur | Gemini İçeriği Oluştur |