Metin

Chat Tamamlama Oluştur

Sohbet mesajı için bir tamamlama oluşturur

POST
/v1/chat/completions

İstek Gövdesi

Desteklenen isteğe bağlı parametreler, kabul edilen değerler ve varsayılanlar seçilen modele bağlıdır. Örnekleme, akıl yürütme veya araç seçeneklerini ayarlamadan önce modelin model ayrıntılarını kontrol edin. Bazı modellerde 1'in üzerindeki n değeri gibi modelin karşılayamadığı bir denetim, 4xx hatasıyla reddedilir. seed veya cezalar gibi ikincil örnekleme denetimleri ise bunun yerine yok sayılabilir.

modelstringzorunlu

Kullanılacak modelin kimliği. Mevcut seçenekler için Modeller sayfasına bakın.

messagesarrayzorunlu

Sohbeti oluşturan mesajların listesi.

Her mesaj nesnesi şunları içerir:

  • role (string): system, developer, user, assistant, tool, function
  • content (string | array | null): Mesaj içeriği

tool_calls içeren bir assistant mesajı için content atlanabilir veya null olarak ayarlanabilir.

content bir dizi olduğunda TokenLab, uyumlu modeller için yapılandırılmış çok modlu blokları destekler:

  • text: { "type": "text", "text": "..." }
  • image: { "type": "image_url", "image_url": { "url": "https://..." } }
  • video: { "type": "video_url", "video_url": { "url": "https://..." } }
  • audio: { "type": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } } veya { "type": "audio_url", "audio_url": { "url": "https://..." } }

Çok modlu girdi için herkese açık olarak erişilebilen https URL'leri kullanın. Görseller ayrıca base64 veri URL'leri olarak da gönderilebilir. Desteklenen medya türleri seçilen modele bağlıdır.

temperaturenumber

Örnekleme sıcaklığı (temperature). Destek, izin verilen değerler ve varsayılan değer seçilen modele bağlıdır; varsayılanını kullanmak için bu alanı atlayın.

max_tokensinteger

Üretilecek maksimum token sayısı. max_tokens veya max_completion_tokens parametrelerinden yalnızca birini gönderin, ikisini birden göndermeyin: başka bir protokol üzerinden sunulan bir model her ikisini de içeren bir isteği reddedebilir.

Düşünen bir modelde, düşünme token'ları bu sınıra dahil edilir. Sınır çok küçükse bütçenin tamamı düşünmeye harcanabilir ve mesaj gövdesi boş kalabilir; kullanılan token'lar yine de faturalandırılır. Sınırı artırın veya modelin izin verdiği durumlarda, örneğin "reasoning_effort": "none" ile düşünmeyi kapatın. deepseek-v4.1-flash (takma adı deepseek-flash) üzerinde "thinking": {"type": "disabled"} da bunu kapatır.

İstek çalıştırılmadan önce TokenLab, bakiyenizin bu maksimum tutarı karşılayıp karşılamadığını kontrol eder. Yanıt kısa olsa bile, çok büyük bir değer düşük bakiyede 402 döndürebilir.

streambooleanvarsayılan: false

True ise, kısmi mesaj farkları sunucu tarafından gönderilen olaylar (SSE) olarak iletilir. Bkz. Streaming.

Uzun çıktılar için (binlerce veya daha fazla token), istemcilerin ve proxy'lerin tam yanıtı beklerken zaman aşımına uğramaması adına stream: true olarak ayarlayın.

stream_optionsobject

Streaming seçenekleri. data: [DONE] öncesinde token kullanımını içeren fazladan bir parça (chunk) almak için include_usage: true olarak ayarlayın. Bu olmadan stream kullanım bilgisi taşımaz.

top_pnumber

Nucleus örnekleme parametresi. Bunu ya da sıcaklığı değiştirmenizi öneririz, ikisini birden değil.

frequency_penaltynumber

-2.0 ile 2.0 arasında bir sayı. Pozitif değerler yinelenen token'ları cezalandırır.

presence_penaltynumber

-2.0 ile 2.0 arasında bir sayı. Pozitif değerler metinde halihazırda bulunan token'ları cezalandırır.

stopstring | array

Durdurma dizisi veya dizilerin listesi. Destek ve dizi sınırları seçilen modele bağlıdır.

toolsarray

Modelin çağırabileceği araçların listesi (function calling). Her araç { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } } biçimindedir. Bkz. Yapılandırılmış çıktılar ve araç çağırma.

tool_choicestring | object

Modelin araçları nasıl kullanacağını denetler. Seçenekler: auto, none, required veya tek bir aracı zorlamak için { "type": "function", "function": { "name": "..." } }.

parallel_tool_callsboolean

Seçilen model tarafından desteklendiğinde, tek bir asistan turunda birden fazla araç çağrısına izin verir.

max_completion_tokensinteger

Düşünme token'ları dahil tamamlama için üst sınır. Daha yeni OpenAI model aileleri tarafından kullanılan max_tokens alternatifidir. İkisinden yalnızca birini gönderin.

reasoning_effortstring

Bunu destekleyen modeller için akıl yürütme çabası. Kabul edilen değerler seçilen modele bağlıdır.

Claude modelleri için bu değer modelin düşünme biçimini belirler: uyarlanabilir düşünme özelliğine sahip modellerde bir çaba düzeyi veya bunu kullanan modellerde bir düşünme bütçesi. none, izin veren modellerde düşünmeyi kapatır. Modelin desteklemediği bir değer 400 hatası ve invalid_value kodu ile reddedilir; hata mesajında desteklenen değerler listelenir. Düşünme açıkken Claude; 1 dışındaki bir temperature, top_k, 0.95–1 aralığı dışındaki bir top_p değerini ve önceden doldurulmuş bir asistan mesajını reddeder. Zorunlu bir tool_choice, uyarlanabilir düşünme ile çalışır ancak bir düşünme bütçesi ile çalışmaz.

anthropic_optionsobject

Claude modelleri için seçenekler.

  • prompt_caching (boolean): İstem başlangıcını önbelleğe almak için true olarak ayarlayın. TokenLab, sistem isteminin sonunu ve en son kullanıcı mesajını önbellek noktaları olarak işaretler. Aynı içerikle başlayan daha sonraki bir istek bunu önbellekten okur. Ya bu seçeneği ya da kendi cache_control işaretlerinizi kullanın, ikisini birden değil.
  • prompt_caching_ttl (string): 5m (varsayılan) veya 1h. İsteği işleyen servis önbelleği bir saat tutamadığında TokenLab, isteği reddetmek yerine beş dakikalık önbelleği kullanabilir.

extra.prompt_caching ve extra.prompt_caching_ttl aynı seçenekler olarak kabul edilir. Fiyatlar ve önbelleğe alınan token'ların nasıl kontrol edileceği için Prompt önbelleğe alma sayfasına bakın.

seedinteger

Destekleyen modeller için örnekleme tohumu (seed). Birebir aynı çıktı garanti edilmez.

ninteger

Üretilecek tamamlama sayısı. Destekleyen modeller 1-128 arasını kabul eder. Birçok model yalnızca 1 değerini destekler.

logprobsboolean

Log olasılıklarının döndürülüp döndürülmeyeceği.

top_logprobsinteger

Döndürülecek en yüksek log olasılıklarının sayısı (0-20). logprobs: true gerektirir.

top_kinteger

Destekleyen modeller için Top-K örnekleme.

response_formatobject

Yanıt biçimi. {"type": "text"} (varsayılan), JSON modu için {"type": "json_object"} veya bir JSON şeması için {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} kullanın. Destek seçilen modele bağlıdır. Bkz. Yapılandırılmış çıktılar ve araç çağırma.

logit_biasobject

Belirtilen token'ların görünme olasılığını değiştirin. Token ID'lerini (dize olarak) -100 ile 100 arasındaki sapma değerleriyle eşleyin. Destek seçilen modele bağlıdır.

service_tierstring

TokenLab, Chat isteklerini standart hizmet katmanında sunar ve faturalandırır. auto ve default kabul edilir. flex veya priority gibi diğer değerler istekten kaldırılır ve istek standart fiyattan faturalandırılır.

userstring

Kötüye kullanım izleme amacıyla son kullanıcınızı temsil eden benzersiz bir tanımlayıcı.

Yanıt

idstring

Tamamlama için benzersiz tanımlayıcı.

objectstring

Her zaman chat.completion.

createdinteger

Tamamlamanın oluşturulduğu anın Unix zaman damgası.

modelstring

Tamamlama için kullanılan model.

choicesarray

Tamamlama seçeneklerinin listesi.

Her seçenek şunları içerir:

  • index (integer): Seçeneğin dizini
  • message (object): Üretilen mesaj
  • finish_reason (string): Modelin neden durduğu; örneğin stop, length, tool_calls veya content_filter

Model düşündüğünde message şunları da içerebilir:

  • reasoning_content (string): Düşünme metni. Bazı modeller yalnızca bir özet döndürür veya hiç metin döndürmez.
  • reasoning_details (array): İmzalarıyla birlikte düşünme blokları. Örneğin bir araç çağrısından sonra düşünme içeren bir konuşmaya devam etmek için, bunları asistan mesajında değiştirmeden geri gönderin.

Bir stream içinde aynı alanlar delta.reasoning_content ve delta.reasoning_details olarak iletilir.

usageobject

Token kullanım istatistikleri.

  • prompt_tokens (integer): İstemdeki token'lar
  • completion_tokens (integer): Düşünme token'ları dahil tamamlamadaki token'lar
  • total_tokens (integer): Kullanılan toplam token sayısı
  • prompt_tokens_details.cached_tokens (integer): Önbellekten okunan istem token'ları
  • cache_creation_input_tokens (integer): Önbelleğe yazılan istem token'ları. Yalnızca değer 0'dan büyük olduğunda bulunur
  • completion_tokens_details.reasoning_tokens (integer): Model bildirdiğinde düşünme token'ları

Bir stream içinde kullanım yalnızca stream_options.include_usage değeri true olduğunda iletilir.

İstek

curl -X POST "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": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

Çok Modlu Örnek

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

Yanıt

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Streaming

stream: true olduğunda yanıt bir text/event-stream olur. Her olay, choices[].delta alanı yeni metni, araç çağrısı argümanlarını veya düşünme metnini taşıyan bir chat.completion.chunk nesnesi içeren data: {...} şeklindedir. Stream data: [DONE] ile sona erer. : ile başlayan satırlar bağlantıyı canlı tutma (keep-alive) yorumlarıdır: bunları yok sayın. [DONE] olmadan veya bir finish_reason olmadan sona eren bir stream tamamlanmamıştır. Bkz. Akış (Streaming).

Hatalar

Hatalar OpenAI tarzı error nesnesini kullanır. Yaygın durumlar: geçersiz bir alan veya modelin kabul etmediği bir değer için 400, geçersiz bir anahtar için 401, yetersiz bakiye için 402, boyut sınırını aşan girdi için 413 ve rate limit için 429. Bkz. API hatalarını işleme.

Yetkilendirme

BearerAuth
AuthorizationBearer <token>

API Anahtarı kimlik doğrulaması. API anahtarlarını Dashboard > API > API Keys bölümünden oluşturun veya yönetin.

Konum: header

Başlıklar

X-TokenLab-Delivery-Policy?string

İstek bazlı Teslimat politikası. API anahtarı ve Çalışma Alanı varsayılanlarını geçersiz kılar. Otomatik olarak önce TokenLab Verified dener ve çıktı, istek kabulü veya kalıcı kaynak oluşturma öncesinde bir kez Official seçeneğine geçiş yapabilir.

Geçerli değerler

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Aynı isteğin ikinci kez çalıştırılmasını engelleyen isteğe bağlı anahtar. Her istek için UUID gibi yeni ve benzersiz bir değer gönderin ve zaman aşımı sonrası yeniden denemeler için bu değeri koruyun. Aynı anahtarla yapılan bir yeniden deneme tekrar çalışmaz: idempotency_replay_unavailable ile 409 hatası veya gövde değiştiğinde genellikle idempotency_conflict hatası döndürür. İstisna: Akış dışı (non-stream) bir sonuç istemci bağlantısı kesildikten sonra tamamlandığında, 24 saat içinde aynı anahtar ve gövde ile yapılan bir yeniden deneme, Idempotent-Replayed: true başlığıyla ve ikinci bir ücretlendirme olmaksızın o sonucu (1 MB'a kadar) döndürür. 255 karakterden uzun bir anahtar yok sayılır ve bu durumda isteğin idempotency koruması olmaz. Bkz: Idempotency anahtarı ile güvenli yeniden deneme.

Uzunluk1 <= length <= 255

İstek gövdesi

application/json

Yanıt

application/json

application/json

application/json

application/json

application/json

application/json

application/json