OpenAI ve Anthropic Uyumlu API Ne Demek? Kodunuzu Değiştirmeden Nasıl Geçersiniz?

"Uyumlu API" ne demek?

Yapay zeka alanında iki biçim fiilen standart haline geldi: OpenAI'nin "Chat Completions" biçimi ve Anthropic'in "Messages" biçimi. Bir API'nin bu biçimlerden birine uyumlu olması, aynı istek yapısını, aynı yanıt yapısını ve aynı hata davranışını sunması demektir. Böylece o biçim için yazılmış her araç (SDK'lar, kütüphaneler, çerçeveler, eklentiler) değişiklik yapmadan çalışır.

Bu çok değerli bir özelliktir, çünkü geliştirici dünyası bu biçimlere göre kodlanmıştır: LangChain, LlamaIndex, Vercel AI SDK, birçok IDE eklentisi, sayısız açık kaynak proje. Uyumlu bir API'ye geçmek, bunların hepsini kullanmaya devam edebilmek anlamına gelir.

Cocorex API, iki biçimi birden destekler:

• POST /v1/chat/completions → OpenAI biçimi
• POST /v1/messages → Anthropic biçimi
• GET /v1/models → model listesi

OpenAI biçimi: kısaca

İstek:

{
  "model": "cocorex-1",
  "messages": [
    {"role": "system", "content": "Kısa ve net cevap ver."},
    {"role": "user", "content": "Merhaba!"}
  ],
  "max_tokens": 500,
  "temperature": 0.7,
  "stream": false
}

Yanıt:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "cocorex-1",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "Merhaba! ..."}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 9, "total_tokens": 21}
}

Sistem talimatı, messages dizisinin içinde system rolüyle verilir. Cevap choices[0].message.content içindedir.

Anthropic biçimi: kısaca

İstek:

{
  "model": "cocorex-1",
  "max_tokens": 500,
  "system": "Kısa ve net cevap ver.",
  "messages": [
    {"role": "user", "content": "Merhaba!"}
  ]
}

Yanıt:

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "content": [{"type": "text", "text": "Merhaba! ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 9}
}

Burada sistem talimatı ayrı bir system alanıdır; max_tokens zorunludur; cevap, bir blok dizisi olan content içinde gelir.

İki biçim arasındaki temel farklar

Cocorex API, Authorization: Bearer başlığını da, x-api-key başlığını da kabul eder; böylece iki SDK da sorunsuz çalışır.

Mevcut kodu iki satırla taşımak

OpenAI SDK (Python)

from openai import OpenAI

client = OpenAI(
    api_key="sk-cocorex-ANAHTARIN",              # 1. satır: anahtar
    base_url="https://api.cocorex-ai.com/v1",   # 2. satır: adres
)

Geri kalan kodunuz (çağrılar, akış, hata yönetimi) aynı kalır.

OpenAI SDK (Node.js)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.COCOREX_API_KEY,
  baseURL: "https://api.cocorex-ai.com/v1",
});

Anthropic SDK (Python)

import anthropic

client = anthropic.Anthropic(
    api_key="sk-cocorex-ANAHTARIN",
    base_url="https://api.cocorex-ai.com",   # /v1 olmadan
)

Ortam değişkenleriyle (kodu hiç değiştirmeden)

Birçok araç, adresi ve anahtarı ortam değişkenlerinden okur:

export OPENAI_BASE_URL="https://api.cocorex-ai.com/v1"
export OPENAI_API_KEY="sk-cocorex-ANAHTARIN"

Bu şekilde, kodunuza hiç dokunmadan, aracı Cocorex API'ye yönlendirebilirsiniz.

Model adları

Uyumlu bir API'de model adı farklıdır; OpenAI'nin gpt-... adlarını burada kullanmazsınız. Cocorex API'de şu modeller vardır:

• cocorex-1: hızlı, dengeli, çok yönlü
• deepseek-4.1-flash: hızlı ve ekonomik; kodlama ve akıl yürütmede güçlü
• gpt-6-astra: karmaşık kod, uzun belge ve derin muhakeme için

Kodunuzda model adını bir yapılandırma değişkeninden okumanız, bunu tek yerden değiştirmenizi sağlar. Tanınmayan bir model adı, hata yerine varsayılan cocorex-1 modeline düşer.

Dikkat edilmesi gereken farklar

"Uyumlu", "her özelliği birebir destekler" anlamına gelmez. Cocorex API'de şunlara dikkat edin:

• Metin odaklı: /v1/chat/completions ucu mesajlarda metin bekler. Görsel gibi çoklu ortam içerikleri, Anthropic biçimindeki /v1/messages ucunda içerik blokları olarak iletilir; destek model ve sağlayıcıya göre değişebilir.
• Araç çağırma (tools): /v1/messages ucu tools alanını iletir. Araç çağıran isteklerde stream: true kullanmanızı öneririz; akışsız modda araç blokları boş dönebilir.
• Model davranışı: Aynı prompt, farklı modellerde farklı cevap verir. Modeli değiştirdikten sonra, kritik promptlarınızı yeniden test edin.
• Sıcaklık ve diğer parametreler: temperature desteklenir; bazı ileri düzey parametreler (ör. logprobs, n) şu an desteklenmeyebilir.
• Hız ve limitler: Yanıt süreleri ve istek hızı, modele ve yüke göre değişir. Zaman aşımı sürelerinizi buna göre ayarlayın.
• Fiyat ve kredi: Kullanım ön ödemeli kredinizden düşer; bakiye bitince 402 döner.

Desteklenen alanların güncel listesi API sayfamızda bulunur.

Taşıma kontrol listesi

1. Konsoldan bir API anahtarı oluşturun.
2. SDK'nızda base URL ve anahtarı değiştirin.
3. Model adını cocorex-1 (veya başka bir Cocorex modeli) yapın.
4. Basit bir isteği Playground'da ve kodunuzda deneyin.
5. Akış kullanıyorsanız, akışı test edin.
6. Hata yönetiminizde 401, 402, 502, 504 kodlarını ele alın.
7. Kritik promptlarınızı yeni modelde kalite açısından kontrol edin.
8. Birkaç gün kullanım grafiğini izleyerek maliyeti doğrulayın.

Neden uyumlu bir API tercih edilir?

• Kilitlenmeyi azaltır: Tek bir sağlayıcıya bağımlı kalmazsınız; geçiş maliyetiniz düşüktür.
• Mevcut ekosistemi kullanırsınız: Yeni bir SDK öğrenmeniz gerekmez.
• Çoklu model deneyebilirsiniz: Modelleri kolayca kıyaslayıp en uygununu seçersiniz.
• Maliyet kontrolü: Ön ödemeli ve şeffaf fiyatlı bir sağlayıcı ile bütçenizi öngörürsünüz.

Diğer dillerde örnekler

Go (standart kütüphane)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    govde, _ := json.Marshal(map[string]any{
        "model": "cocorex-1",
        "messages": []map[string]string{{"role": "user", "content": "Merhaba!"}},
    })
    istek, _ := http.NewRequest("POST", "https://api.cocorex-ai.com/v1/chat/completions", bytes.NewReader(govde))
    istek.Header.Set("Authorization", "Bearer "+os.Getenv("COCOREX_API_KEY"))
    istek.Header.Set("Content-Type", "application/json")

    cevap, err := http.DefaultClient.Do(istek)
    if err != nil { panic(err) }
    defer cevap.Body.Close()
    veri, _ := io.ReadAll(cevap.Body)
    fmt.Println(string(veri))
}

PHP (cURL)

<?php
$ch = curl_init("https://api.cocorex-ai.com/v1/chat/completions");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("COCOREX_API_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "model" => "cocorex-1",
    "messages" => [["role" => "user", "content" => "Merhaba!"]],
  ]),
]);
$cevap = json_decode(curl_exec($ch), true);
echo $cevap["choices"][0]["message"]["content"];

Ruby (Net::HTTP)

require "net/http"
require "json"

uri = URI("https://api.cocorex-ai.com/v1/chat/completions")
istek = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{ENV['COCOREX_API_KEY']}", "Content-Type" => "application/json")
istek.body = { model: "cocorex-1", messages: [{ role: "user", content: "Merhaba!" }] }.to_json
cevap = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(istek) }
puts JSON.parse(cevap.body).dig("choices", 0, "message", "content")

Anthropic biçiminde ham cURL

curl https://api.cocorex-ai.com/v1/messages \
  -H "x-api-key: sk-cocorex-ANAHTARIN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"cocorex-1","max_tokens":300,"system":"Kısa cevap ver.","messages":[{"role":"user","content":"Merhaba!"}]}'

Geçiş sırasında karşılaşılabilecek sorunlar

Akış olaylarını işlemek

OpenAI biçimi: Her olay data: {json} satırıdır; choices[0].delta.content metin parçasını taşır; son olay data: [DONE].

Anthropic biçimi: Olaylar event: ve data: çiftleridir. Metin parçaları content_block_delta olayında delta.text içindedir; message_delta olayı bitiş nedenini ve token kullanımını taşır.

Resmî SDK'lar bu ayrıştırmayı sizin için yapar; elle işliyorsanız, olayları boş satıra (\n\n) göre bölüp JSON'u dikkatle ayrıştırın ve beklenmeyen olay tiplerini yok sayın.

Çok sağlayıcılı mimari kurmak

Uyumlu API'nin en büyük avantajlarından biri, kodunuzda sağlayıcıyı yapılandırmayla değiştirebilmenizdir:

SAGLAYICI = {
    "cocorex": {"base_url": "https://api.cocorex-ai.com/v1", "key_env": "COCOREX_API_KEY", "model": "cocorex-1"},
    # başka bir OpenAI uyumlu sağlayıcı da aynı yapıyla eklenebilir
}

Bu yapıyla; bir sağlayıcı kesintiye uğrarsa yedeğe geçebilir, modelleri A/B test edebilir ve maliyetleri karşılaştırabilirsiniz. Hata durumunda otomatik yedeğe geçiş (failover) için yeniden deneme mantığınıza ikinci bir sağlayıcı ekleyin.

Sık sorulan sorular

OpenAI SDK'sının tüm yöntemleri çalışır mı? Sohbet tamamlama (chat.completions) ve model listeleme çalışır. Embeddings, görsel üretimi, ses gibi diğer OpenAI uçları şu an sunulmuyor.

Anthropic'in araç/görsel özellikleri? /v1/messages ucu tools ve içerik bloklarını iletir; destek modele ve sağlayıcıya bağlıdır; akışla kullanmanızı öneririz.

Hangi uç daha iyi? Mevcut kodunuz hangisini kullanıyorsa onu kullanın; ikisi aynı modellere ve aynı faturalamaya erişir.

Eski modeli yeni bir modelle değiştirdim, sonuçlar değişti. Normaldir; modeller farklıdır. Kritik prompt'ları yeniden test edip gerekirse sistem talimatını uyarlayın.

Geçişi kademeli yapabilir miyim? Evet; trafiğin küçük bir yüzdesini Cocorex'e yönlendirip kalite, hız ve maliyeti karşılaştırın, sonra artırın.

Sonuç

Uyumlu bir API, bir geçişi iki satırlık bir değişikliğe indirger. Cocorex API ile OpenAI veya Anthropic SDK'nızı olduğu gibi kullanır, yalnızca adresi ve anahtarı değiştirirsiniz. Başlamak için ilk istek rehberimize bakın, maliyetleri öngörmek için maliyet rehberimizi okuyun.