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.
| Parametre | Tür | Notlar |
|---|---|---|
model | dize (zorunlu) | /v1/models listesindeki etkin kısa adlardan herhangi biri. |
messages | dizi (zorunlu) | Standart OpenAI mesaj biçimi. |
temperature | 0..2 | Örnekleme sıcaklığı. Varsayılan değer 1. Bu tablonun altında listelenen modeller üzerinde etkisi yoktur. |
top_p | 0..1 | Çekirdek örneklemesi. temperature için belirtilen istisna burada da geçerlidir. |
max_tokens | int | Çıktı sınırı; ikisi birden gönderildiğinde max_ ö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. |
stream | bool | Parçaları SSE olarak akış hâlinde gönderir. Aşağıya bakın. |
tools | array | İşlev / araç tanımları. Hem Claude hem GPT araç kullanımını destekler. |
tool_choice | auto| | Belirli bir aracı zorunlu kılın veya modelin karar vermesine izin verin. |
response_ | object | JSON çı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_ | string | Yalnızca GPT modellerinde reasoning. olarak iletilir. Claude'a iletilmez. Akıl yürütme bölümüne bakın. |
seed | int | Desteklendiği yerlerde deterministik örnekleme. |
stop | string|array | Kesin durdurma dizileri. |
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)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:
| Aile | json_schema | json_object |
|---|---|---|
| Claude | Zorunlu kılınır. Anthropic'in yapılandırılmış çıktıları (output_) 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. |
| GPT | Responses 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 schemaClaude ile ilgili bilinmesi gereken dört nokta:
- Şema, yazdığınıza neredeyse aynen uygun biçimde Anthropic'e gönderilir. Anthropic nesnelerde
additionalProperties: falseolmasını zorunlu tutar; bu nedenle Kunavo, özellikleri listelenen her nesneye bunu ekler ve değerini ayarlamaz — Pydantic'inmodel_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,falsedışında herhangi bir değere ayarlanmışsa veya hiçbir özellik listelenmediği hâldeadditionalPropertiesayarlanmamışsa) veoneOf— bunun yerineanyOfkullanın. Geri kalanlar Anthropic'in yapılandırılmış çıktılar sayfasında listelenir. strictvenameyok sayılır: Anthropic kabul ettiği her şemayı, katı olsun veya olmasın, zorunlu kılar.- Şema, son
assistantmesajıyla (ön doldurma) birlikte kullanılamaz; Anthropic 400 hatası verir. max_tokensnesnenin ortasında tükenirse JSON kesilir vefinish_reasondeğ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:
| Aile | reasoning_ | Kullanımdaki akıl yürütme token'ları |
|---|---|---|
| GPT | Responses API'nin reasoning. 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_ içine dâhil edilir ve completion_ 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_ — bu nedenle reasoning_, 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_ içinde sayar; completion_ 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)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)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:
| Alan | Anlam |
|---|---|
prompt_ | Faturalandırdığımız giriş belirteçleri; önbelleğe alınan belirteçler dahildir. |
prompt_ | Önbelleğe alınan giriş — prompt_ |
completion_ | Faturalandırdığımız çıktı token'ları. GPT modellerinde bunlara akıl yürütme token'ları dahildir; Claude'da bunlar Anthropic'in output_ |
completion_ | GPT modellerinde completion_ |
total_tokens | prompt_ |
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:
| Özellik | Ollama v1 | Kunavo v1 |
|---|---|---|
| Uç nokta yolu | /v1/ | /v1/ |
| Akış | SSE, chat. | Aynı — delta yapısı aynı |
| Araç çağrısı | tools / tool_calls | Claude ve GPT genelinde aynı |
| Görsel girdisi | Çok modlu yerel modellerde image_url blokları | Aynı bloklar; URL veya base64 veri URI'si |
| api_key | Yer tutucu, yok sayılır | Gerç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_ |
| Sohbetin ötesinde | completions, embeddings | Ayrıca görüntü, video ve ses uç noktaları |
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.