Yapay zekâ API'si nedir, token nedir? Yeni başlayanlar için

Sohbet uygulaması ile API arasındaki fark

Bir sohbet uygulaması, hazır bir vitrindir: ekranda bir kutu vardır, yazarsınız, cevap gelir. Konuşma geçmişi, ayarlar ve görünüm uygulama tarafından yönetilir. API (uygulama programlama arayüzü) ise aynı modele kendi programınızdan, bir web adresine düz metin hâlinde istek göndererek ulaşmanın yoludur. Arada ekran yoktur; ne gönderdiğinizi ve gelen cevabı ne yapacağınızı siz belirlersiniz.

Bu fark pratikte şuna yarar: bir dosyadaki yüzlerce satırı tek tek özetletmek, kendi web sitenize bir yardımcı eklemek ya da bir betiğin içinden modele soru sormak API ile mümkündür. Karşılığında, sohbet uygulamasının sizin yerinize yaptığı bazı işleri (örneğin önceki mesajları hatırlamak) kendiniz üstlenirsiniz.

İstek ve yanıt: model, messages ve roller

Çoğu yapay zekâ API'si, "chat completions" adıyla bilinen aynı temel kalıbı kullanır. OpenRouter'ın belgelerine göre istek, https://openrouter.ai/api/v1/chat/completions adresine gönderilen bir POST isteğidir ve gövdesinde iki temel alan bulunur [1]:

• model: Hangi modelin cevap vereceği. Değer, sağlayıcı önekiyle birlikte yazılır.
• messages: Konuşmanın kendisi. Her mesajın bir role (rol) ve bir content (içerik) alanı vardır.

Roller üç tanedir:

• system: Modele genel talimat verir; örneğin "Kısa ve Türkçe cevap ver."
• user: Sizin sorunuz ya da isteğiniz.
• assistant: Modelin daha önce verdiği cevaplar.

API, kendi başına önceki konuşmayı hatırlamaz. Sohbeti sürdürmek istiyorsanız, önceki user ve assistant mesajlarını her yeni istekte listeye yeniden eklersiniz. Yanıt tarafında ise model cevabı choices adlı bir dizinin içinde gelir; OpenRouter bu alanın, tek cevap olsa bile her zaman bir dizi olduğunu belirtir [1]. Yanıtta ayrıca usage alanı bulunur ve kaç token harcandığını gösterir.

Token nedir?

Dil modelleri metni harf harf ya da kelime kelime değil, token denen parçalar hâlinde işler. Anthropic'in sözlüğüne göre token, bir dil modelinin en küçük birimidir ve bir kelimeye, kelime parçasına, tek bir karaktere ya da bayta karşılık gelebilir [2]. Uzun ya da seyrek kelimeler genelde birkaç parçaya bölünür; sık geçen kısa kelimeler tek token olabilir.

Kaba bir ölçü olarak OpenAI, İngilizce metinde bir tokenın yaklaşık 4 karaktere ya da 0,75 kelimeye denk geldiğini söyler [3]. Ancak bu yalnız İngilizce için bir tahmindir. Anthropic de token sayısının kullanılan dile ve içerik türüne göre değiştiğini açıkça not eder [2][4].

Diller arasındaki fark küçük değildir. Akademik bir çalışma, aynı içeriğin farklı dillerde tokenlara bölündüğünde uzunluğunun 15 kata kadar değişebildiğini göstermiştir [5]. Başka bir çalışma da API'lerin token başına ücret aldığını, bu yüzden bazı dillerin konuşucularının aynı bilgi için daha fazla ödeme yaptığını tespit etmiştir [6]. Türkçenin bu tabloda tam olarak nerede durduğu modele ve kullanılan tokenizer'a göre değişir; en güvenilir yol, kendi metninizi gönderip yanıttaki usage sayılarına bakmaktır. Aynı firmanın modelleri arasında bile fark olabilir: Anthropic, yeni modellerinde kullandığı tokenizer'ın aynı metin için yaklaşık yüzde 30 daha fazla token ürettiğini belirtmektedir [4].

Giriş tokenı, çıkış tokenı ve fiyat

Bir istekte iki tür token sayılır. Giriş tokenları sizin gönderdiğiniz her şeydir: system talimatı, önceki mesajlar ve yeni sorunuz. Çıkış tokenları ise modelin ürettiği cevaptır. OpenRouter yanıtında bunlar prompt_tokens ve completion_tokens olarak, toplamı da total_tokens olarak döner [1].

Fiyatlar tek tek token için değil, milyon token başına verilir. OpenRouter'ın sık sorulan sorular sayfası, her model ve sağlayıcının milyon token başına farklı bir fiyatı olduğunu ve giriş ile çıkış tokenlarının genellikle ayrı fiyatlandırıldığını söyler [7]. Anthropic'in fiyat tablosunda da her model için giriş ve çıkış ayrı sütunlardadır ve çıkış fiyatı girişin birkaç katıdır; tabloda "MTok" kısaltması "milyon token" anlamına gelir [4].

Hesap basittir: kullanılan token sayısı, milyon token fiyatıyla çarpılıp bir milyona bölünür. Uzun bir sohbeti her seferinde baştan gönderdiğiniz için, konuşma uzadıkça giriş tokenlarının da büyüdüğünü unutmayın.

Bağlam penceresi kısaca

Anthropic, bağlam penceresini modelin yeni metin üretirken geriye dönüp bakabildiği metin miktarı, yani bir tür "çalışma belleği" olarak tanımlar [2]. OpenAI'nin belgeleri ise bunu daha somut ifade eder: gönderdiğiniz metin ile üretilen cevabın toplamı, modelin en büyük bağlam uzunluğunu aşamaz [3]. Çok uzun bir belgeyi ya da çok uzamış bir sohbeti gönderdiğinizde istek bu yüzden reddedilebilir veya cevap için az yer kalabilir.

Ücretsiz modeller: fiyat yok, istek limiti var

Bazı platformlar, ücretsiz modeller sunar. Bu modellerde milyon token fiyatı yerine bir istek limiti uygulanır. OpenRouter'ın belgelerine göre adı :free ile biten ücretsiz model sürümlerinde dakikada en fazla 20 istek gönderilebilir. Günlük sınır ise hesaba bugüne kadar alınan krediye bağlıdır: 10 krediden az alındıysa günde 50 istek, en az 10 kredi alındıysa günde 1000 istek [8]. Aynı sayfa, yuvarlama ve yükleme ücretlerini karşılamak için yüksek limitin 9 kredide başladığını da not eder.

OpenRouter ayrıca openrouter/free adlı bir yönlendirici sunar; bu, istekleriniz için uygun bir ücretsiz modeli kendisi seçer [7]. Ücretsiz modellerin listesine ücretsiz modeller sayfamızdan, ayrıntılı kullanıma OpenRouter'da ücretsiz model kullanımı yazımızdan, diğer sağlayıcılarla kıyasa da ücretsiz yapay zekâ API karşılaştırması yazımızdan bakabilirsiniz.

Küçük bir curl örneği

Aşağıdaki komut, terminalden OpenRouter'a tek bir istek gönderir. API anahtarınızı koda yazmak yerine OPENROUTER_API_KEY adlı bir ortam değişkeninde tutmanız daha güvenlidir; komut anahtarı oradan okur. İstek biçimi ve yetkilendirme başlığı OpenRouter'ın API belgesine dayanır [1].

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/free",
    "messages": [
      {"role": "system", "content": "Kısa ve Türkçe cevap ver."},
      {"role": "user", "content": "Token nedir, bir cümleyle anlat."}
    ]
  }'

Cevap JSON biçiminde gelir. Modelin yazdığı metin choices dizisinin ilk elemanındaki message.content alanındadır; usage bölümünde de bu tek isteğin kaç giriş ve çıkış tokenı tuttuğunu görürsünüz. Aynı soruyu birkaç farklı biçimde sorup bu sayıların nasıl değiştiğini izlemek, tokenları anlamanın en hızlı yoludur.

Sonuç

Bir yapay zekâ API'si, sohbet uygulamasının arkasındaki modele doğrudan ulaşmanızı sağlar: hangi modeli kullanacağınızı model ile, konuşmayı ise rollerle işaretlenmiş messages listesiyle belirtirsiniz. Ücretli modellerde maliyet, giriş ve çıkış tokenlarının milyon token fiyatıyla çarpılmasıyla hesaplanır; ücretsiz modellerde ise sınırı istek limitleri çizer. Token sayısı dile ve modele göre değiştiği için, Türkçe metinlerinizde gerçek tüketimi görmenin en iyi yolu küçük bir deneme isteği gönderip usage alanına bakmaktır.