Neden 'OpenAI compatible' ifadesi LLM API'ları arasında tam bir entegrasyon sözleşmesi değildir

Tek etiket, dört protokol

XiuRouter çok modelli gateway'inin arkasındaki şirket XiuAI'nin dev.to'da yayımladığı bir yazı, "OpenAI compatible" etiketinin kullanışlı bir kısaltma olduğunu, ancak bir entegrasyon sözleşmesi oluşturmadığını savunuyor. İki client aynı API anahtarını ve base domain'i paylaşırken farklı istek yolları, kimlik doğrulama başlıkları, payload yapıları, streaming olayları ve tool-call formatları gönderebilir. Bu fark, coding agent'ler, SDK'lar veya üretim uygulamaları birden fazla sağlayıcıyı önünde konumlandıran bir gateway'e bağlandığında görünür hale gelir.

XiuRouter'ın kendisi dört metin üretimi rotası sunuyor: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages ve Gemini GenerateContent. Yazının merkezindeki kural, client'ın gerçekten konuştuğu protokolü seçmek; model adından veya uyumluluk rozetinden çıkarılanı değil. Bir servis grubunda Chat Completions üzerinden erişilebilen bir modelin Responses, Messages veya GenerateContent üzerinden çalışacağı garanti değildir.

Rotayı client'a göre eşleştirin

Yazının yönlendirme önerisine göre Codex, agent'ler ve daha yeni OpenAI tarzı uygulamalar Responses rotasına; Claude Code ve Anthropic SDK'ları Anthropic Messages'a; Responses desteği olmayan mevcut OpenAI uyumlu uygulamalar Chat Completions'a; Gemini SDK'ları ise GenerateContent'a aittir. Client dokümantasyonu belirsizse, yazar genel bir uyumluluk rozetine güvenmek yerine client'ın resmi yapılandırma kılavuzuna veya istek loglarına bakılmasını öneriyor.

Base URL tuzakları

Sık görülen bir yanlış yapılandırma, client'ların URL'leri nasıl oluşturduğuna ilişkindir. OpenAI uyumlu SDK'lar genellikle /v1 yolunu kendileri ekler, dolayısıyla yapılandırılan base URL bunu içermelidir. /v1/messages ekleyen bir Claude client'ına ya da /v1beta/models/... ekleyen bir Gemini client'ına bunun yerine çıplak API kökü verilmelidir. Konvansiyonların karıştırılması /v1/v1/messages gibi yinelenen yollar üretir; yazı bunu, bir domain mi, bir base path mi yoksa tam bir endpoint mi beklendiğini belirtmeyen "API URL" etiketli yapılandırma alanlarına bağlıyor.

Doğrudan istekler için dört yol şunlardır: POST /v1/chat/completions, POST /v1/responses, POST /v1/messages ve POST /v1beta/models/{model}:generateContent.

Kimlik doğrulama protokolden protokole değişir

Kimlik doğrulama da protokole özgüdür. OpenAI uyumlu istekler bir Authorization: Bearer başlığı kullanır. Anthropic Messages, x-api-key ile birlikte bir anthropic-version başlığı kullanır ve XiuRouter bu rotada Claude Code gibi gateway client'ları için Bearer token'ı da kabul eder. Gemini, x-goog-api-key ve key query parametresini kabul eder; ancak yazı, query string'deki anahtarların erişim loglarına ve kopyalanan URL'lere sızabileceği için başlıkları tercih ediyor.

Tam üretim kombinasyonunu doğrulayın

Yazı, uygulama trafiğini taşımadan önce, kullanılacak API anahtarı, model ID'si, servis grubu, protokol, streaming modu ve gereken tool ya da yapılandırılmış çıktı özelliklerinin tam kombinasyonuyla tek küçük bir istek gönderilmesini öneriyor. Önce kapsamlı anahtara görünür modelleri listeleyin, sonra hedeflenen rota üzerinden minimal bir istek gönderin, ardından sonucu kullanım kayıtlarında doğrulayın: anahtar, model, servis grubu, endpoint, token sayıları, durum ve maliyet. Testin kendisi ücretlidir, bu yüzden önce güncel fiyatlara bakılmalıdır.

Bilinen uyumluluk sınırları

Bir gateway rotası, her sağlayıcı özelliğini uygulamadan temel metin işlemeyi destekleyebilir. XiuRouter'ın bildirdiği sınırlar arasında özel bir /v1/messages/count_tokens rotasının bulunmaması yer alıyor (Claude Code token sayımını isteğe bağlı olarak ele alıyor ve çıkarıma geri düşebilir, ancak uçtan uca görevin yine de doğrulanması gerekiyor). Responses rotası stateless'tir; bu nedenle saklanan konuşmalar, previous_response_id, arka plan modu ve sağlayıcı tarafından barındırılan tool'lar kapsam dışıdır. Gateway, Gemini Interactions API yerine Gemini GenerateContent'ı sunar; dosyalar, fine-tuning, görsel varyasyonlar ve bazı eski endpoint'ler uygulanmamıştır. Gelen bir istek yukarı akış sağlayıcısının formatına dönüştürüldüğünde tool çağrıları, yapılandırılmış çıktı, prompt caching, streaming olayları ve token muhasebesi de değişebilir.

Kapsamlı anahtarlarla daha güvenli geçişler

Yazı, uygulama veya ortam başına bir anahtar öneriyor; model, servis grubu, kota, son kullanma tarihi ve IP kapsamıyla sınırlanmış. Geçiş için mevcut sağlayıcıyı yapılandırılmış tutun, gateway'i ayrı bir sağlayıcı veya ortam olarak ekleyin, kritik olmayan küçük bir görevi test edin, çıktıyı, streaming'i, tool çağrılarını, token muhasebesini, gecikmeyi ve maliyeti karşılaştırın, ardından önceki sağlayıcıyı geri alma yolu olarak tutarak trafiği kademeli olarak taşıyın.

Neden önemli

Çoğu ekip "OpenAI compatible" ifadesini bir onay kutusu olarak görüyor ve bu yazı, bu varsayımın nerede başarısız olduğuna dair pratik bir katalog: istek yolları, auth başlıkları, durum yönetimi, token sayımı ve tool-call dönüşümü. Çok modelli gateway'ler coding agent'ler ile sağlayıcılar arasında giderek daha fazla konumlandıkça, uyumsuzluklar bozuk yeniden denemeler, yarım kalan agent görevleri veya client beklentileriyle uyuşmayan kullanım kayıtları olarak ortaya çıkıyor. Çıkarılan ders XiuRouter'ın ötesine genelleniyor: client'ınızın gerçekten gönderdiği protokolü belirleyin, üretime gidecek tam kombinasyon üzerinde test edin ve asla bir base URL değişikliğini tam uyumluluğun kanıtı olarak görmeyin.