Yapay zekâ API'si nedir, ne işe yarar? Meraklılar için giriş

Bir e-ticaret sitesinde müşteri hizmetleri sorumlususunuz. Her gün yüzlerce müşteri yorumu geliyor ve bunları elle "olumlu", "olumsuz", "kargo şikâyeti" diye ayırmak saatler alıyor. Sohbet asistanına yorumları tek tek yapıştırarak denediniz, işe yaradı, ama günde beş yüz yorum için bu yöntem sürdürülebilir değil. Yazılımcı bir arkadaşınız "API ile otomatikleştirirsin" diyor ve siz bunun ne demek olduğunu tam bilmiyorsunuz.

Ya da üniversitede bilgisayar dışı bir bölümde okuyorsunuz, ama merak ediyorsunuz: Bu yapay zekâ özellikli uygulamalar, not uygulamalarındaki özetleme düğmeleri, müşteri hizmetleri botları nasıl çalışıyor? Çoğunun arkasında aynı şey var: bir yapay zekâ API'si. Bu rehber, hiç kod yazmamış ama mantığı anlamak ve ilk denemesini yapmak isteyenler için. Sonunda kendi bilgisayarınızdan bir yapay zekâ modeline mesaj gönderip yanıt almış olacaksınız.

API'yi bir restoran siparişi gibi düşünün

API (Uygulama Programlama Arayüzü), iki yazılımın birbiriyle belirli kurallarla konuşmasını sağlayan bir kapıdır. Restoran örneğiyle düşünün: Siz mutfağa girmezsiniz; garsona belirli bir biçimde sipariş verirsiniz, garson mutfağa iletir, yemek size gelir. API'de sizin programınız "sipariş" yani istek gönderir, yapay zekâ sağlayıcısının sunucusu modeli çalıştırır ve size yanıt döner.

Sohbet ekranı ile API arasındaki fark şudur: Sohbet ekranı insanın kullanması için tasarlanmış bir arayüzdür. API ise programların kullanması içindir. Aynı modele erişirsiniz, ama API ile bunu otomatikleştirebilir, kendi uygulamanıza, Excel tablonuza, web sitenize ya da bir otomasyon aracına bağlayabilirsiniz.

API'nin tipik kullanım alanları:

• Yüzlerce müşteri yorumunu otomatik sınıflandırmak.
• Kendi web sitenize ya da uygulamanıza yapay zekâ özelliği eklemek.
• Belgelerden belirli bilgileri çıkarıp tabloya yazmak.
• Bir iş akışını otomasyon araçlarıyla birbirine bağlamak.

Token: Yapay zekânın para birimi

Yapay zekâ modelleri metni harf harf ya da kelime kelime değil, "token" adı verilen parçalar hâlinde işler. Bir token bazen bir kelime, bazen kelimenin bir parçası, bazen bir noktalama işaretidir. Türkçe gibi eklemeli dillerde bir kelime çoğu zaman birden fazla token'a bölünür; "gidemeyeceklerdi" gibi bir kelime birkaç parçaya ayrılabilir. Kesin bölünme modelden modele değişir.

Token neden önemli? Üç nedenle:

• Ücret: API ücretleri genellikle token sayısına göre hesaplanır. Gönderdiğiniz metin (giriş) ve modelin ürettiği metin (çıkış) çoğu zaman farklı fiyatlandırılır; çıkış genellikle daha pahalıdır. Güncel fiyatları sağlayıcının fiyat sayfasından kontrol edin.
• Sınır: Her modelin bir seferde işleyebileceği toplam token miktarı (bağlam penceresi) sınırlıdır.
• Hız: Uzun yanıtlar daha uzun sürer.

Pratik ipucu: Sağlayıcıların çoğu yanıtın içinde kaç token harcandığını size söyler. İlk denemelerinizde bu sayıya bakmayı alışkanlık edinin.

İstek ve yanıt nasıl görünür?

Bu rehberdeki örnekler, pek çok sağlayıcının desteklediği "OpenAI uyumlu sohbet tamamlama" biçimini kullanıyor. Bu biçim yaygın olduğu için öğrendiğiniz mantık başka sağlayıcılarda da büyük ölçüde işe yarar; ancak adres, model adı ve bazı alanlar sağlayıcıdan sağlayıcıya farklıdır. Her zaman kullandığınız sağlayıcının belgelerine bakın.

Bir istek dört temel parçadan oluşur:

• Adres (endpoint): İsteğin gönderileceği URL.
• Kimlik doğrulama: API anahtarınız, genellikle `Authorization: Bearer ANAHTAR` başlığıyla gönderilir.
• Model adı: Hangi modeli kullanmak istediğiniz.
• Mesajlar: Rolü belirtilmiş mesaj listesi. `system` modelin genel davranışını, `user` sizin mesajınızı, `assistant` modelin önceki yanıtlarını temsil eder.

Önemli bir nokta: API "durumsuzdur". Model önceki isteğinizi hatırlamaz. Sohbeti sürdürmek istiyorsanız önceki mesajları her istekte yeniden göndermeniz gerekir. Bu da token harcamasını artırır.

Adım adım: İlk isteğinizi gönderin

1. Sağlayıcı seçin ve hesap açın: Bir yapay zekâ sağlayıcısının geliştirici sitesinde hesap açın. Sohbet uygulamasının aboneliği ile API kullanımı çoğu zaman ayrı faturalandırılır; birine ödeme yapmanız diğerini kapsamayabilir.

2. Harcama sınırı koyun: Daha anahtar oluşturmadan, faturalandırma ya da kullanım bölümünde aylık harcama sınırı ve uyarı eşiği tanımlayın. Bazı sağlayıcılar ön ödemeli kredi sistemiyle çalışır; o durumda küçük bir miktar yükleyin. Menü adları sağlayıcıya göre değişir.

3. API anahtarı oluşturun: Panelden yeni bir anahtar oluşturun ve anlamlı bir ad verin ("deneme-bilgisayarim" gibi). Anahtar çoğu zaman yalnızca bir kez gösterilir; güvenli bir yere kaydedin. Mümkünse anahtara yalnızca gereken izinleri verin.

4. Anahtarı ortam değişkenine koyun: Anahtarı kodun içine yazmak yerine bilgisayarınızın ortam değişkenine kaydedin. macOS ya da Linux terminalinde:

export OPENAI_API_KEY="anahtarınızı-buraya-yapıştırın"
export MODEL_ADI="sağlayıcınızın-belgelerindeki-model-adı"

Windows PowerShell'de:

$env:OPENAI_API_KEY = "anahtarınızı-buraya-yapıştırın"
$env:MODEL_ADI = "sağlayıcınızın-belgelerindeki-model-adı"

Bu komutlar yalnızca o terminal penceresi açık kaldığı sürece geçerlidir. Kalıcı yapmanın yolları işletim sistemine göre değişir.

5. curl ile ilk isteği gönderin: curl, macOS, Linux ve güncel Windows sürümlerinde genellikle hazır gelen bir komut satırı aracıdır. Aşağıdaki komut macOS ve Linux terminalinde çalışır. Adres OpenAI'nin sohbet tamamlama adresidir; başka bir OpenAI uyumlu sağlayıcı kullanıyorsanız onun belgelerindeki adresle değiştirin.

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "'"$MODEL_ADI"'",
    "messages": [
      {"role": "system", "content": "Kısa ve net Türkçe yanıt veren bir yardımcısın."},
      {"role": "user", "content": "Token nedir? İki cümleyle açıkla."}
    ],
    "max_tokens": 150
  }'

`max_tokens` alanı yanıtın en fazla ne kadar uzun olabileceğini sınırlar; maliyet kontrolü için faydalıdır. Bazı yeni modeller bu alan yerine farklı bir ad kullanabilir, hata alırsanız sağlayıcının belgelerine bakın.

6. Python ile aynı isteği gönderin: Python yüklüyse önce `requests` kütüphanesini kurun:

pip install requests

Ardından aşağıdaki kodu `ilk_istek.py` adıyla kaydedin ve aynı terminalden `python ilk_istek.py` ile çalıştırın:

import os
import requests

API_ADRESI = "https://api.openai.com/v1/chat/completions"
anahtar = os.environ["OPENAI_API_KEY"]
model = os.environ["MODEL_ADI"]

istek = {
    "model": model,
    "messages": [
        {"role": "system", "content": "Kısa ve net Türkçe yanıt veren bir yardımcısın."},
        {"role": "user", "content": "Token nedir? İki cümleyle açıkla."},
    ],
    "max_tokens": 150,
}

yanit = requests.post(
    API_ADRESI,
    headers={"Authorization": f"Bearer {anahtar}"},
    json=istek,
    timeout=60,
)
yanit.raise_for_status()
veri = yanit.json()

print(veri["choices"][0]["message"]["content"])
print("Kullanılan token:", veri.get("usage"))

Kod, anahtarı ortam değişkeninden okur, isteği gönderir, bir hata varsa durur ve yanıt metni ile token kullanımını yazdırır.

Örnek çıktı: Yanıtı okumayı öğrenin

curl isteğinin yanıtı kısaltılmış olarak şuna benzer:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "...",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Token, yapay zekâ modellerinin metni işlerken kullandığı küçük parçalardır. Bir kelime tek bir token olabileceği gibi birden fazla token'a da bölünebilir."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 41,
    "total_tokens": 73
  }
}

Bakmanız gereken üç yer var: `choices[0].message.content` yanıt metnidir. `finish_reason` değeri `stop` ise model yanıtını doğal olarak bitirmiştir; `length` ise `max_tokens` sınırına takılıp yarıda kesilmiştir. `usage` ise kaç token harcadığınızı gösterir. Sayılar her istekte değişir; buradakiler yalnızca örnektir.

İlk denemede yanıt `length` ile yarıda kesilmişti, çünkü `max_tokens` değerini 30 vermiştim. Değeri 150'ye çıkardım ve system mesajına "en fazla iki cümle" kuralını ekledim; böylece hem yanıt tamamlandı hem de gereksiz uzunluk önlendi. Ders: Uzunluğu yalnızca `max_tokens` ile değil, talimatla da kontrol edin.

API'yi yapay zekâya öğretmen olarak kullanın

Kod yazmayı bilmiyorsanız sohbet asistanı bu yolculukta en iyi yardımcınız olur. Aşağıdaki komutlar işinize yarar:

Python'u bilgisayarıma yeni kurdum ve hiç kod yazmadım. Aşağıdaki Python kodunu satır satır, her satırın ne yaptığını bir lise öğrencisine anlatır gibi açıkla. Özellikle os.environ, requests.post ve veri["choices"][0]["message"]["content"] kısımlarına odaklan.

[yukarıdaki ilk_istek.py kodunu buraya yapıştırın]

Python ile OpenAI uyumlu bir sohbet tamamlama API'si kullanıyorum. musteri_yorumlari.csv adında, tek sütunlu ("yorum" başlıklı) bir dosyam var. Her yorumu API'ye gönderip "olumlu", "olumsuz" veya "nötr" etiketi alan ve sonucu etiketli_yorumlar.csv dosyasına yazan bir kod yaz. Anahtarı ve model adını ortam değişkeninden okusun, her istekte max_tokens 5 olsun, hata olursa o satırı atlayıp ekrana yazsın ve en sonda toplam token kullanımını göstersin. Kodun her bölümünü kısa yorumlarla açıkla.

API'den şu hatayı aldım: "401 Unauthorized". Kodumu ve terminalde yaptıklarımı aşağıya yazıyorum (anahtarımı sildim). Hatanın olası nedenlerini en olasıdan başlayarak sırala ve her biri için nasıl kontrol edeceğimi adım adım anlat.

Kimin işine nasıl yarar? Üç senaryo

Konya'da e-ticaret sitesinde çalışan Büşra: Müşteri yorumlarını sınıflandırmak istiyor. Yukarıdaki CSV komutu tam onun için. İlk denemeyi 20 yorumluk küçük bir dosyayla yapıp sonuçları elle kontrol etmesi, sonra tüm dosyaya geçmesi en güvenli yol.

İstanbul'da bağımsız çevirmen Tolga: Terim tutarlılığını kontrol etmek için kendi sözlüğünü kullanan bir araç istiyor.

Ben serbest çevirmenim. Python ile OpenAI uyumlu bir API'ye istek gönderen bir betik istiyorum: terimler.txt dosyasındaki "İngilizce = Türkçe" satırlarını okusun, ceviri.txt dosyasındaki Türkçe metni bu terimlere göre kontrol etsin ve sözlüğe uymayan yerleri satır numarasıyla listelesin. System mesajında modele yalnızca tutarsızlıkları listelemesini, metni yeniden yazmamasını söyle.

Adana'da lise bilişim öğretmeni Kemal: Öğrencilerine API mantığını anlatmak istiyor.

Lise 11. sınıf öğrencilerime yapay zekâ API'sinin mantığını 40 dakikalık bir derste anlatacağım. Restoran sipariş benzetmesini kullanan, token kavramını tahtada gösterebileceğim bir etkinlik içeren ve sonunda API anahtarı güvenliğine dair 3 kural veren bir ders planı hazırla. Öğrenciler gerçek anahtar kullanmayacak; örnek istek ve yanıtı kâğıt üzerinde inceleyecekler.

Anahtar güvenliği: Pazarlıksız kurallar

API anahtarı, hesabınıza bağlı bir kredi kartı gibidir. Sızarsa başkası sizin adınıza harcama yapabilir.

• Anahtarı kodun içine yazmayın; ortam değişkeni ya da `.env` dosyası kullanın.
• `.env` dosyası kullanıyorsanız onu `.gitignore` dosyasına ekleyin ki GitHub gibi platformlara yüklenmesin. Herkese açık depolara sızan anahtarlar çok kısa sürede kötüye kullanılabilir.
• Anahtarı tarayıcıda çalışan koda (bir HTML sayfasının içine) asla koymayın; sayfayı açan herkes görebilir.
• Anahtarı e-postayla, mesajla, ekran görüntüsüyle paylaşmayın; yapay zekâya hata sorarken bile kodunuzdaki anahtarı silin.
• Her proje için ayrı anahtar oluşturun ki biri sızarsa yalnızca onu iptal edin.
• Bir anahtarın sızdığından şüphelenirseniz panelden hemen iptal edin ve yenisini oluşturun.

Sık yapılan hatalar

Harcama sınırı koymadan başlamak. Döngüye giren bir kod ya da sızan bir anahtar, fark etmeden ciddi fatura çıkarabilir. Doğrusu: İlk iş sınır ve uyarı tanımlamak.

Sohbet aboneliğinin API'yi kapsadığını sanmak. Çoğu sağlayıcıda bunlar ayrı ürünlerdir. Doğrusu: API faturalandırmasını ayrıca kontrol edin.

Tüm sohbet geçmişini her seferinde göndermek. Uzun sohbetlerde her istek öncekilerin hepsini taşıdığı için maliyet hızla büyür. Doğrusu: Gerekmeyen eski mesajları kırpın ya da özetleyip gönderin.

Binlerce isteği bir anda göndermek. Sağlayıcıların istek hızı sınırları vardır; aşınca 429 hatası alırsınız. Doğrusu: Önce küçük bir örnekle deneyin, sonra istekler arasına kısa beklemeler koyun.

Model çıktısını doğrulamadan kullanmak. Model yanlış etiketleyebilir ya da istenen biçime uymayabilir. Doğrusu: Çıktının beklediğiniz değerlerden biri olup olmadığını kodda kontrol edin ve örneklem üzerinden elle denetleyin.

Takıldığınızda

401 hatası: Anahtar yanlış, eksik, iptal edilmiş ya da ortam değişkeni o terminalde tanımlı değil. Terminalde `echo $OPENAI_API_KEY` ile (ekranı kimseyle paylaşmadan) değişkenin dolu olup olmadığını kontrol edin.

404 ya da model bulunamadı hatası: Model adı yanlış yazılmış ya da hesabınızın o modele erişimi yok. Sağlayıcının model listesine bakın.

429 hatası: İstek hızı sınırına ya da kota sınırına takıldınız. Bir süre bekleyin, isteklerin arasına bekleme koyun ve faturalandırma durumunuzu kontrol edin.

Windows'ta curl komutu çalışmıyorsa: Yukarıdaki curl örneği macOS ve Linux terminali içindir; Windows'ta tırnak kullanımı farklıdır. En kolay yol Python örneğini kullanmaktır.

Yanıt boş ya da yarıda kesik: `finish_reason` değerine bakın; `length` ise `max_tokens` değerini artırın.

İleri seviye ipuçları

Yapılandırılmış çıktı isteyin. Modelden serbest metin yerine JSON biçiminde yanıt istemek, çıktıyı kodla işlemeyi kolaylaştırır. Bazı sağlayıcılar bunun için özel parametreler sunar; desteklenip desteklenmediğini belgelerden kontrol edin.

Sıcaklık ayarını öğrenin. `temperature` parametresi yanıtların ne kadar çeşitli olacağını etkiler. Sınıflandırma gibi tutarlılık gereken işlerde düşük, yaratıcı metinlerde daha yüksek değerler denenir.

Önbellek ve toplu işleme seçeneklerine bakın. Bazı sağlayıcılar acil olmayan toplu işler ya da tekrar eden uzun girişler için daha uygun maliyetli seçenekler sunar. Ayrıntılar sağlayıcıya göre değişir.

Kullanımı kaydedin. Her isteğin `usage` bilgisini bir dosyaya yazın. Bir hafta sonra hangi işin ne kadar token harcadığını görmek, maliyeti düşürmenin en etkili yoludur.

Sık sorulan sorular

API kullanmak için yazılımcı olmak gerekir mi?

Hayır. Temel bir curl ya da Python örneğini çalıştırmak için yazılımcı olmanız gerekmez. Ancak gerçek bir uygulama geliştirirken hata yönetimi, güvenlik ve maliyet kontrolü önem kazanır; büyük projelerde deneyimli birinden destek alın.

API ile müşteri verisi göndermek güvenli mi?

Sağlayıcının veri kullanım ve saklama politikasını mutlaka okuyun. Kişisel verileri işliyorsanız KVKK kapsamındaki yükümlülükleri göz önünde bulundurun ve mümkünse verileri anonimleştirin. Kurumsal kullanımda hukuk ve bilgi güvenliği birimlerinize danışın.

Hangi sağlayıcıyı seçmeliyim?

İhtiyacınıza, bütçenize ve kullanmak istediğiniz modele bağlı. Başlangıç için belgeleri anlaşılır, harcama sınırı koymaya izin veren ve küçük denemelere uygun bir sağlayıcı seçin. Fiyatlar ve modeller sık değiştiği için karşılaştırmayı güncel bilgilerle yapın.

API ile sohbet uygulaması arasında sonuç farkı olur mu?

Olabilir. Sohbet uygulamaları arka planda ek talimatlar, araçlar ve ayarlar kullanabilir. API'de bu ayarların çoğunu siz belirlersiniz; bu yüzden aynı soruya farklı yanıt almanız normaldir.

Hazır şablon

Python ile OpenAI uyumlu sohbet tamamlama API'si kullanan bir betik yaz.
Amaç: [betiğin yapacağı iş]
Girdi: [dosya adı ve biçimi, örneğin tek sütunlu CSV]
Çıktı: [dosya adı ve biçimi]
System mesajı: [modelin rolü ve kuralları]
Sınırlar: max_tokens [sayı], istekler arası [saniye] bekleme, en fazla [sayı] satır işle.
Anahtarı ve model adını ortam değişkeninden oku, hataları yakala, sonunda toplam token kullanımını yazdır. Her bölümü kısa yorumlarla açıkla.

Bugün deneyin

Bugün yalnızca iki şey yapın: Bir sağlayıcıda hesap açıp önce harcama sınırını koyun, sonra yukarıdaki Python örneğini çalıştırın. Ekranda yapay zekânın yanıtını ve altında harcadığınız token sayısını gördüğünüz an, sohbet ekranının arkasındaki dünyaya ilk adımı atmış olacaksınız. Ardından kendi küçük işinizi düşünün: Hangi tekrar eden görevi bir sonraki hafta otomatikleştirebilirsiniz?