Chat Completions

Sohbet tamamlama API'si

Chat Completions API, konuşma tabanlı AI uygulamaları oluşturmanızı sağlar. Mesaj geçmişi göndererek bağlamsal ve tutarlı yanıtlar alabilirsiniz.

POST /v1/chat/completions

Verilen mesaj geçmişi için bir model yanıtı oluşturur.

Request Body

model string zorunlu

Kullanılacak modelin ID'si. Örnek: google/gemini-3.8-flash, anthropic/claude-sonnet-5.5, openai/gpt-6-luna

messages array zorunlu

Konuşma geçmişini içeren mesaj dizisi. Her mesaj role ve content alanlarını içermelidir.

temperature number opsiyonel

0 ile 2 arasında bir değer. Daha yüksek değerler daha yaratıcı, düşük değerler daha tutarlı yanıtlar üretir. Varsayılan: 0.7

max_tokens integer opsiyonel

Yanıtta üretilecek maksimum token sayısı. Düşünen (reasoning) modellerde düşünme tokenleri de bu sınıra sayılır; çok küçük bir değer yanıtı yarıda kesebilir (finish_reason: "length"). Gönderilmezse bakiye ön kontrolü modelin azami çıktı tokenına göre yapılır; düşük bakiyede 402 almamak için uygun bir üst sınır verin.

stream boolean opsiyonel

true olarak ayarlandığında, yanıtlar Server-Sent Events olarak gerçek zamanlı akıtılır. Varsayılan: false

top_p number opsiyonel

Nucleus sampling parametresi. 0 ile 1 arasında. Varsayılan: 1

max_completion_tokens integer opsiyonel

OpenAI'nin max_tokens için yeni adı. max_tokens gönderilmezse onun yerine geçer; ikisi birlikte gelirse max_tokens geçerlidir. Bazı modeller çok küçük değerleri kendi alt sınırına (ör. 16) yükseltir.

stop string | array opsiyonel

Üretimin duracağı en fazla 4 dizi (metin ya da metin dizisi). Düşünen modellerde dizi düşünce metninde de eşleşebilir ve yanıt content: null ile bitebilir; bazı modeller (ör. OpenAI'nin düşünen modelleri) stop alanını yok sayar.

tools array opsiyonel

Modelin çağırabileceği fonksiyonlar (OpenAI tools biçimi). Model bir araç çağırırsa yanıtta choices[0].message.tool_calls gelir ve finish_reason değeri tool_calls olur. Aracın sonucunu bir sonraki istekte role: "tool" ve tool_call_id ile gönderin. Akışta araç çağrısı delta.tool_calls parçaları olarak gelir. Araç tanımları girdi tokeni olarak ücretlendirilir.

tool_choice string | object opsiyonel

auto (varsayılan), none, required ya da belirli bir fonksiyon: {"type": "function", "function": {"name": "..."}}. parallel_tool_calls alanı da iletilir.

response_format object opsiyonel

{"type": "json_object"} geçerli bir JSON nesnesi döndürür; {"type": "json_schema", "json_schema": {"name": "...", "strict": true, "schema": {...}}} şemaya uygun JSON döndürür. İsteğinizde JSON istediğinizi ayrıca belirtin. Düşünen modellerde max_tokens değerini düşünme payını da karşılayacak kadar yüksek tutun; aksi halde JSON yarıda kesilebilir (finish_reason: "length").

reasoning_effort string opsiyonel

Düşünme düzeyi: none, minimal, low, medium, high. Düşünen modellerde etkilidir, desteklemeyen modellerde yok sayılır. none düşünmeyi kapatır (daha hızlı ve ucuz yanıt). Düşünme tokenleri çıktı tokeni olarak ücretlendirilir.

reasoning object opsiyonel

Ayrıntılı düşünme ayarı: {"effort": "low"}, {"max_tokens": 1024} ya da {"exclude": true}. Gönderilirse reasoning_effort yerine bu geçerlidir. Model düşünce metni ürettiyse yanıtta message.reasoning alanında (akışta delta.reasoning) gelir.

Not: n (birden çok seçim), logprobs, top_logprobs, logit_bias, seed ve user alanları ücretli modellerde şu an iletilmez; yanıtta tek seçim döner. top_k, frequency_penalty ve presence_penalty iletilir. Ücretsiz Türkiye modellerinin (:tr) ek parametreleri için Türkiye modelleri bölümüne bakın.

Model Adları ve Takma Adlar

account_balance_wallet

Bakiye ön kontrolü: İstek modele gitmeden önce tahmini tavan maliyet bakiyenizle karşılaştırılır. Tahmin, girdi ile max_tokens değerinden (gönderilmezse modelin azami çıktı tokenından) hesaplanır ve %20 güvenlik payı eklenir; bakiye bunun altındaysa 402 döner. Ücret her zaman gerçek kullanımdan kesilir. Ayrıntı: Hata Kodları.

Mesaj Rolleri

Role Açıklama
system Asistanın davranışını belirleyen sistem talimatı
user Kullanıcıdan gelen mesajlar
assistant Asistanın önceki yanıtları

Örnek İstek

cURL 
curl https://api.onysoft.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ony-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.8-flash",
    "messages": [
      {
        "role": "system",
        "content": "Sen yardımcı bir asistansın."
      },
      {
        "role": "user",
        "content": "Python'da liste nasıl oluşturulur?"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 2000
  }'

Örnek Yanıt

JSON 
{
  "id": "req_a1b2c3d4e5f6a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "google/gemini-3.8-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Python'da liste oluşturmanın birkaç yolu vardır:\n\n1. Köşeli parantez ile:\n```python\nmy_list = [1, 2, 3, 4, 5]\n```\n\n2. list() fonksiyonu ile:\n```python\nmy_list = list((1, 2, 3))\n```"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 95,
    "total_tokens": 123
  },
  "cost": {
    "amount": 0.000061,
    "currency": "USD"
  },
  "success": true,
  "data": { /* geriye uyum: yukarıdaki alanların aynısı (id, object, created, model, choices, usage, cost) */ }
}

Akışsız yanıtlarda OpenAI alanları (id, choices, usage …) üst seviyededir; resmî OpenAI SDK'ları ve LangChain gibi kütüphaneler response.choices[0].message.content ile doğrudan okur. Geriye uyum için yanıtta "success": true ve aynı içerik data altında da bulunur; data.choices okuyan mevcut entegrasyonlar değişmeden çalışır. Yeni entegrasyonlarda üst seviyedeki alanları kullanın. İsteğin ücreti cost.amount alanında (USD) yazar. Görsel ya da ses üreten akışsız yanıtlarda resmî SDK'lar dışındaki istemciler, yanıt boyutu iki katına çıkmasın diye yalnız "success": true + data biçimini alır.

Size uygun modeli bulmanıza yardımcı olayım mı?