Dokümantasyon

Dokümantasyon

Sohbet tamamlamaları

Kunavo'nun /v1/chat/completions uç noktası, Claude ve GPT aileleri için OpenAI'nin sohbet tamamlama protokolünü kullanır. Akış, araçlar ve JSON çıktısı aynı SDK üzerinden çalışır; reasoning_effort parametresinin işlevi aileye bağlıdır ve bu sayfada açıklanır.

Uç nokta: POST /v1/chat/completions. İstek ve yanıt biçimleri, akış ve isteğe bağlı tool_calls / reasoning_tokens alanları dâhil, OpenAI'nin sohbet tamamlama API'siyle tam olarak eşleşir.

Temel çağrı

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "You are a senior staff engineer."},
        {"role": "user", "content": "Pros and cons of postgres LISTEN/NOTIFY for a job queue?"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)

Parametreler

Tüm standart OpenAI parametreleri kabul edilir. Bazıları yalnızca belirli sağlayıcılar için anlamlıdır — çevirici, her üst sağlayıcının desteklediği alanları iletir.

ParametreTürNotlar
modeldize (zorunlu)/v1/models listesindeki etkin kısa adlardan herhangi biri.
messagesdizi (zorunlu)Standart OpenAI mesaj biçimi.
temperature0..2Örnekleme sıcaklığı. Varsayılan değer 1. Bu tablonun altında listelenen modeller üzerinde etkisi yoktur.
top_p0..1Çekirdek örneklemesi. temperature için belirtilen istisna burada da geçerlidir.
max_tokensintÇıktı sınırı; ikisi birden gönderildiğinde max_completion_tokens önceliklidir. GPT modellerinde akıl yürütme token'ları bu sınıra dâhildir. Her ikisi de gönderilmeyen Claude isteklerinde değer 4.096 olur.
streamboolParçaları SSE olarak akış hâlinde gönderir. Aşağıya bakın.
toolsarrayİşlev / araç tanımları. Hem Claude hem GPT araç kullanımını destekler.
tool_choiceauto|none|namedBelirli bir aracı zorunlu kılın veya modelin karar vermesine izin verin.
response_formatobjectJSON çıktısı. Claude'da json_schema zorunlu kılınır, json_object ise kılınmaz — tüm aileler için JSON çıktısı bölümüne bakın.
reasoning_effortstringYalnızca GPT modellerinde reasoning.effort olarak iletilir. Claude'a iletilmez. Akıl yürütme bölümüne bakın.
seedintDesteklendiği yerlerde deterministik örnekleme.
stopstring|arrayKesin durdurma dizileri.
Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7 ve Claude Sonnet 5, temperature, top_p veya top_k parametrelerini kabul etmez. Kunavo, sağlayıcının 400 hatasını size döndürmek yerine bu modellere gönderilen isteklerden üçünü de kaldırır; dolayısıyla bu modellerde üçünün de etkisi olmaz.

Akış

stream=True değerini ayarlayın. Kunavo, sunucudan gönderilen olayları OpenAI'nin tam biçiminde üretir: her parça, choices[0].delta.content içeren bir chat.completion.chunk olur. Son kullanım yükü data: [DONE] ile gelir.

stream = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Explain B-trees in one paragraph."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
Akış, tüm sohbet modellerinde çalışır. Anthropic protokolünü kullanan Claude üst sağlayıcısında Anthropic olay akışını anlık olarak OpenAI delta'larına çeviririz — SDK'nız farkı anlamaz.

Araç / işlev çağırma

Araç çağırma, sağlayıcılar arasında çalışır. Araçları JSON şeması olarak tanımlayın; model mesajında tool_calls döndürür; bunları yürütüp sonuçları role: "tool" mesajları olarak geri iletirsiniz.

tools = [{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto",
)

# Inspect tool calls the model wants to make
for call in resp.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

JSON çıktısı (response_format)

response_format, JSON çıktısı ister. Her ailenin isteği farklı bir üst sağlayıcı mekanizmasına çevrildiğinden, neyi garanti ettiği model ailesine bağlıdır:

Ailejson_schemajson_object
ClaudeZorunlu kılınır. Anthropic'in yapılandırılmış çıktıları (output_config.format) olarak gönderilir; yanıt belirttiğiniz şemaya uyar. Kunavo'nun sunduğu her Claude modelinde kontrol edilmiştir, 2026-09-24.Zorunlu kılınmaz. Anthropic'te şemasız JSON modu yoktur; bu nedenle istek kabul edilir ancak yok sayılır — yanıt düz yazıyla veya kod bloğuyla başlayabilir.
GPTResponses API'nin text.format alanı olarak iletilir; ancak mevcut üst sağlayıcı bunu her istekte uygulamaz. Ayrıştırmadan önce doğrulayın.text.format olarak iletilir.
import json

resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Jane Doe <jane@example.com> wants the Pro plan."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "signup",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan": {"type": "string", "enum": ["free", "pro", "enterprise"]},
                },
                "required": ["name", "email", "plan"],
                "additionalProperties": False,
            },
        },
    },
)
signup = json.loads(resp.choices[0].message.content)  # constrained to the schema

Claude ile ilgili bilinmesi gereken dört nokta:

  • Şema, yazdığınıza neredeyse aynen uygun biçimde Anthropic'e gönderilir. Anthropic nesnelerde additionalProperties: false olmasını zorunlu tutar; bu nedenle Kunavo, özellikleri listelenen her nesneye bunu ekler ve değerini ayarlamaz — Pydantic'in model_json_schema() aracı da bu şekilde üretir. Anthropic'in hâlâ reddettiği durumlar şunlardır; 400 hatasında sorunu belirtir: açık bırakılmış bir nesne (additionalProperties, false dışında herhangi bir değere ayarlanmışsa veya hiçbir özellik listelenmediği hâlde additionalProperties ayarlanmamışsa) ve oneOf — bunun yerine anyOf kullanın. Geri kalanlar Anthropic'in yapılandırılmış çıktılar sayfasında listelenir.
  • strict ve name yok sayılır: Anthropic kabul ettiği her şemayı, katı olsun veya olmasın, zorunlu kılar.
  • Şema, son assistant mesajıyla (ön doldurma) birlikte kullanılamaz; Anthropic 400 hatası verir.
  • max_tokens nesnenin ortasında tükenirse JSON kesilir ve finish_reason değeri "length" olur.

Görsel / çok kipli girdi

vision özelliğine sahip modeller görsel içerik bloklarını kabul eder. HTTPS URL'si veya data: base64 URI'si kullanın.

# Pass an image URL or a base64 data URI as part of a multimodal message
resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {
                "url": "https://example.com/cat.jpg"
            }},
        ],
    }],
)
print(resp.choices[0].message.content)

Katalogdaki görsel işleyebilen modeller arasında Claude Opus 5.5 bulunur — diğerleri için model listesine bakın.

HTTPS görseli için Kunavo dosyayı kendisi indirip doğrudan modele verir; çünkü bazı üst sağlayıcılar doğrudan görsel URL'sini yok sayar. Sınırlar: istek başına 16 görsel, görsel başına 5 MB, toplamda 20 MB, indirme başına 10 saniye. Alınamayan bir görsel atlanmak yerine adını belirten bir hata döndürür.

Akıl yürütme

Bu uç noktadaki akıl yürütme denetiminin işlevi aileye bağlıdır; çünkü her ailenin isteği farklı bir üst sağlayıcı API'sine çevrilir:

Ailereasoning_effortKullanımdaki akıl yürütme token'ları
GPTResponses API'nin reasoning.effort alanı olarak GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, GPT-5.6 Terra ve GPT-5.5 üzerinde değer değiştirilmeden iletilir. Kabul edilen değerler modele özgüdür; GPT-6 Sol ve GPT-6 Luna'da none akıl yürütmeyi kapatır, max ise en yüksek düzeydir.completion_tokens içine dâhil edilir ve completion_tokens_details.reasoning_tokens olarak ayrı gösterilir; çıktı ücreti üzerinden faturalandırılır.
Claudeİletilmez. Anthropic isteği sabit bir alan listesinden oluşturulur — model, max_tokens, messages, stream, temperature, top_p, top_k, stop, tools, tool_choice ve response_format — bu nedenle reasoning_effort, thinking ve bu listenin dışındaki diğer her şey burada düşürülür.Ayrı döküm yoktur. Anthropic, tüm düşünme token'larını output_tokens içinde sayar; completion_tokens de bunu bildirir.
# GPT models: reasoning_effort is forwarded as the Responses API's
# reasoning.effort. Reasoning tokens are part of completion_tokens.
resp = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Plan a 3-week MLOps migration."}],
    reasoning_effort="high",
)
details = resp.usage.completion_tokens_details   # absent when no reasoning ran
print(details.reasoning_tokens if details else 0)
Claude'da genişletilmiş düşünme, Anthropic'e özgü Messages API üzerinden çalışır; bu API thinking alanını Anthropic'e çevirmeden aktarır.

İstem önbelleğe alma

Uzun bir sistem istemi, bir referans belgesi, birkaç örnekli bir blok — sabit kalan herhangi bir önek üst tarafta önbelleğe alınabilir ve sonraki çağrılarda giriş fiyatının çok daha düşük bir kısmı karşılığında yeniden kullanılabilir. Önbellek isabetleri kullanım nesnesinde prompt_tokens_details.cached_tokens olarak görünür.

GPT modelleri otomatik olarak önbelleğe alır; istekte değişiklik yapmanız gerekmez. cached_tokens, prompt_tokens öğesinin bir alt kümesidir ve daha düşük bir önbellek okuma ücretiyle faturalandırılır.

Claude yalnızca bir cache_control kesme noktasına kadar önbelleğe alır ve uzun bir istemde bu uç nokta kesme noktalarını sizin için ayarlar: sistem isteminde, araç tanımlarında ve konuşma bir asistan turu içerdiğinde son mesajda. Öneki kendiniz seçmek için aşağıdaki gibi cache_control alanını bir içerik bloğuna ekleyin; Kunavo sizin kesme noktalarınızı korur ve yalnızca boş bıraktığınız konumlara kendi kesme noktalarını ekler:

# Claude caches prefixes you mark with cache_control. Attach it to a content
# block; later calls reusing that prefix read it at ~10% of the input price.
resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LONG_DOCUMENT,            # the stable, reused prefix
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Summarize the document above."},
        ],
    }],
)
print(resp.usage.prompt_tokens_details.cached_tokens)
Claude istemini önbelleğe alma üzerinde tam kontrol için — sistem istemini ve araç tanımlarını önbelleğe alma, birden fazla kesme noktası ve Anthropic'in kendi cache_creation_input_tokens / cache_read_input_tokens kullanım alanları dahil — Anthropic'in kendi Messages API'sini kullanın. Bu uç nokta da sistem istemini ve araç tanımlarını önbelleğe alır, tek bir istekte birden fazla kesme noktası kabul eder ve önbelleğe yazmaları cache_creation_input_tokens, önbellekten okumaları prompt_tokens_details.cached_tokens olarak bildirir; yalnızca Anthropic'in kendi uç noktasının yaptığı şey, istek gövdenizi hiçbir kesme noktası eklemeden iletmektir.

Kullanım nesnesi

Her yanıt (ve akışın son parçası) bir usage nesnesi içerir:

AlanAnlam
prompt_tokensFaturalandırdığımız giriş belirteçleri; önbelleğe alınan belirteçler dahildir.
prompt_tokens_details.cached_tokensÖnbelleğe alınan giriş — prompt_tokens değerinin bir alt kümesidir ve daha düşük bir önbellek okuma ücretiyle faturalandırılır.
completion_tokensFaturalandırdığımız çıktı token'ları. GPT modellerinde bunlara akıl yürütme token'ları dahildir; Claude'da bunlar Anthropic'in output_tokens değeridir.
completion_tokens_details.reasoning_tokensGPT modellerinde completion_tokens içindeki akıl yürütme payı. Sıfır olduğunda bulunmaz ve Claude için raporlanmaz.
total_tokensprompt_tokens + completion_tokens.

Ollama OpenAI uyumluluğu — /v1/chat/completions

Ollama, yerel modellerini http://localhost:11434/v1 adresindeki OpenAI uyumlu bir API üzerinden sunar ve bu sayfada belgelenen aynı /chat/completions sözleşmesini uygular. Böylece istemci tarafında ikisi birbirinin yerine kullanılabilir: Ollama'nın v1 API'si için yazılan her şey, temel URL'yi ve modeli değiştirerek Kunavo API'sinde çalışır.

from openai import OpenAI

# Before — Ollama's OpenAI-compatible API, local models
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",                       # ignored locally
)
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

# After — the same call against hosted frontier models.
# Two lines changed. Everything below them is untouched.
client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # <- was localhost:11434/v1
    api_key=os.environ["KUNAVO_API_KEY"],
)
resp = client.chat.completions.create(
    model="claude-sonnet-5",  # <- was llama3.2
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)

Sağlayıcı değiştirirken genellikle sorun çıkaran parçalar burada sorun çıkarmaz, çünkü kullanılan kablo biçimi aynıdır:

ÖzellikOllama v1Kunavo v1
Uç nokta yolu/v1/chat/completions/v1/chat/completions
AkışSSE, chat.completion.chunkAynı — delta yapısı aynı
Araç çağrısıtools / tool_callsClaude ve GPT genelinde aynı
Görsel girdisiÇok modlu yerel modellerde image_url bloklarıAynı bloklar; URL veya base64 veri URI'si
api_keyYer tutucu, yok sayılırGerçek bir Kunavo anahtarı
modelİndirilmiş bir etiket (llama3.2)Barındırılan bir kısa ad (claude-sonnet-5)
usage ek alanlarıYalnızca belirteç sayılarıcached_tokens ve reasoning_tokens ekler
Sohbetin ötesindecompletions, embeddingsAyrıca görüntü, video ve ses uç noktaları
Her ikisini de mi kullanıyorsunuz? base_url, model ve anahtarı ortam değişkenlerinden okuyup ortama göre geçiş yapın — çevrimdışı geliştirme için yerel modeller, kalitenin önemli olduğu yerlerde barındırılan modeller; tümünde tek bir kod yolu. Ollama'nın OpenAI arayüzünün neleri uyguladığı ve neleri uygulamadığı dahil olmak üzere tüm adımlar Ollama OpenAI uyumlu API kılavuzunda açıklanıyor.

Ollama'nın OpenAI uyumlu /v1/chat/completions uç noktası için resmî belgeler nerede?

Ollama, OpenAI uyumluluk katmanını kendi deposundaki docs/openai.md dosyasında belgelendirir; bu, yerel sunucunun hangi OpenAI alanlarını uyguladığına dair yetkili başvuru kaynağıdır. Bu sayfa, Kunavo'nun barındırılan /v1/chat/completions uç noktası için aynı nitelikte bir başvuru kaynağıdır: yukarıda alan alan belgelenen aynı OpenAI sohbet tamamlama sözleşmesi; böylece iki yüzeyi doğrudan karşılaştırabilirsiniz. Kısaca, istek ve yanıt biçimleri aynıdır — Ollama bunu yerel olarak çekilen modeller için http://localhost:11434/v1 adresinde, Kunavo ise barındırılan Claude ve GPT modelleri için https://api.kunavo.com/v1 adresinde sunar.

Kunavo'nun /v1/chat/completions uç noktası Ollama'nın OpenAI API'siyle uyumlu mu?

Evet — ikisi de aynı OpenAI sohbet tamamlama sözleşmesini uygular; bu nedenle Ollama'nın http://localhost:11434/v1 adresi için yazılmış bir istemci, https://api.kunavo.com/v1 adresinde hiçbir değişiklik yapılmadan çalışır. İstek alanları (messages, temperature, max_tokens, stream, tools, tool_choice, response_format, stop, seed) ve yanıt alanları (choices[].message, akışlarda choices[].delta, usage) eşleşir. Farklar, barındırılan modellerden bekleyeceğiniz türdendir: api_key bir yer tutucu değil gerçek bir anahtardır, model llama3.2 gibi yerel olarak çekilmiş bir etiket yerine claude-sonnet-5 gibi barındırılan bir kısa ad alır ve usage, yerel modellerin bildirmediği cached_tokens ile reasoning_tokens alanlarını içerir.

Bir Ollama uygulamasını barındırılan Claude veya GPT'ye nasıl geçiririm?

İki satırı değiştirin: base_url değerini http://localhost:11434/v1 yerine https://api.kunavo.com/v1 olarak ayarlayın ve model değerini yerel etiketten barındırılan bir kısa ada çevirin. Ollama'nın yok saydığı yer tutucu yerine gerçek bir Kunavo anahtarı kullanın. SSE ve tool_calls biçimleri aynı olduğundan akış, araç çağırma ve görsel anlama kod yollarında değişiklik gerekmez.

Geliştirme için Ollama'yı, üretimde barındırılan modelleri kullanmaya devam edebilir miyim?

Evet; bu yaygın bir kurulumdur — base URL, model ve anahtarı ortam değişkenlerinden okuyup ortama göre değiştirin. Her iki uç da aynı OpenAI protokolünü kullandığından sürdürülecek ikinci bir kod yolu olmaz: çevrimdışı geliştirme için yerel Llama veya Qwen, kalitenin önemli olduğu durumlarda barındırılan Claude veya GPT. Araç tanımları ve akış işleyicileri aynen paylaşılır.

Kunavo, Ollama'nın uyumlu yüzeyine hangi OpenAI uç noktalarını ekliyor?

Ollama'nın OpenAI uyumlu yüzeyi /chat/completions, /completions, /embeddings ve /models uç noktalarını kapsar. Kunavo aynı anahtara medya uç noktalarını ekler: /v1/images/generations, /v1/images/edits, /v1/video/generations, /v1/videos ve /v1/audio/music; ayrıca Anthropic'e özgü /v1/messages uç noktasında Claude'u sunar. Diğer yönde dürüstçe belirtilmesi gereken iki nokta: /v1/audio/speech, /v1/audio/transcriptions ve /v1/embeddings veri iletim biçimleri olarak uygulanmıştır, ancak şu anda arkalarında etkin bir model yoktur; bu nedenle bugün başarılı olmazlar — ayrıca Ollama'nın aksine Kunavo modelleri yerel olarak çalıştırmaz. Hangi modellerin çağrılabildiğini her zaman GET /v1/models belirler.

Sonraki adımlar