OpenAI uyumlu API rehberi — Ollama'nın yerel endpoint'inden barındırılan frontier modellerine

"OpenAI uyumlu", bir API'nin OpenAI'nin /v1/chat/completions ile aynı kablo biçimini konuştuğu anlamına gelir — bu nedenle herhangi bir OpenAI SDK'sı veya aracı yalnızca base_url değiştirilerek bununla çalışır. Ollama, makinenizde yerel olarak çalışan modeller için OpenAI uyumlu bir uç nokta sunar. Kunavo ise Claude, GPT ve görsel, video ve ses modelleri gibi barındırılan son teknoloji modeller için tek bir bearer token arkasında bir uç nokta sunar. Bu kılavuz, yaklaşımı ve kodu yeniden yazmadan aralarında nasıl geçiş yapılacağını gösterir.

"OpenAI uyumlu" ne anlama gelir?

OpenAI Chat Completions biçimi fiilî standart haline gelmiştir: girişte bir messages dizisi, çıkışta bir choices[].message, akış için Server-Sent Events ve işlev çağırma için tools. Bu sözleşmeye uyan her uç nokta "OpenAI uyumlu"dur ve resmî openai SDK'ları (Python, Node ve tüm topluluk portları) base_url ayarlanarak ona yönelir.

Ollama yaklaşımı (yerel)

Ollama açık modelleri yerelde çalıştırır ve şu adreste sunar: http://localhost:11434/v1:

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Aynı kod, barındırılan son teknoloji modeller (Kunavo)

Aynı SDK'yı Kunavo'ya yönlendirip bir son teknoloji model seçin. Yalnızca base_url, api_key ve model değişir — çağrı byte düzeyinde aynıdır:

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

/app/keys adresinden anahtar alın; hızlı başlangıçta Node ve curl biçimleri bulunur.

Yerel ve barındırılan — hangisi ne zaman kullanılmalı

Yaygın bir kurulum: çevrimdışı geliştirme için localhost üzerinde Ollama, üretimde barındırılan kalite için Kunavo — tek bir ortam değişkeni bunlar arasında geçiş yapar. Her iki tarafın uyguladığı alan bazlı sözleşme (parametreler, akış farkları, tool_calls, usage nesnesi ve Ollama'nın v1 yüzeyiyle eşdeğerlik tablosu) için /v1/chat/completions referansına ve Ollama OpenAI uyumluluğu bölümüne bakın.

Modelleri çalışma zamanında keşfetme

Ollama'nın /api/tags özelliği gibi Kunavo da OpenAI biçimli bir katalog sunar. Slug'ları sabit kodlamak yerine çalışma zamanında çözümleyin:

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

Sohbetin ötesinde

Aynı anahtar görsel (/v1/images/generations), video (/v1/video/generations) ve ses uç noktalarına ulaşır — hepsi OpenAI biçimindedir. Kunavo'nun diğer ağ geçitlerinden farkı için çok modlu yapay zekâ kılavuzuna ve OpenRouter karşılaştırmasına bakın.

Alışılmış "uyumlu" tanımının ötesine geçen ve bilinmesi gereken bir yüzey daha vardır: POST /v1/responses. Codex CLI, özel sağlayıcıyı yalnızca Responses API üzerinden kabul eder; bu nedenle OpenAI uyumlu ağ geçitlerinin çoğu onu hiç çalıştıramaz — Codex'in token başına maliyetini açıklayan sayfa, bunu çalışan bir yapılandırma bloğuyla ele alır. Önbelleğe alınmış girdiyi de içeren bir GPT iş yükünün fiyatını hesaplamak için OpenAI API fiyatlandırma hesaplayıcısı kendi token sayılarını alır.

Sık sorulan sorular