AI API Nasıl Kullanılır?

Bu derste yapay zekâ modellerini kendi uygulamalarınıza, betiklerinize veya web sitenize bağlamanın yolunu, yani AI API kullanımını sıfırdan anlatıyoruz: gereksinimler, ilk isteği gönderme, temel parametreler, maliyet mantığı ve sık yapılan hatalar. Konunun temelindeki kavramı API nedir? dersimizde ayrıntısıyla işledik; burada o bilgiyi yapay zekâ modellerine uygulayacağız. Ünitenin tamamına Yapay Zekâ dersleri kategorimizden ulaşabilirsiniz.

AI API Nedir, Ne İşe Yarar?

ChatGPT, Claude veya Gemini gibi araçlarda modeli bir sohbet penceresinden kullanırsınız. AI API ise aynı modele programınız üzerinden bağlanmanın yoludur: siz bir istek gönderirsiniz, model size metin olarak yanıt döner. Farkı bir örnekle verelim: sohbet arayüzü tek kişilik bir araçtır; API sayesinde aynı modeli binlerce kullanıcılı bir uygulamanın içine, bir müşteri destek botuna ya da gelen e-postaları özetleyen bir betiğe gömebilirsiniz. OpenAI, Anthropic ve Google gibi şirketler modellerini bu API'ler üzerinden sunar; API'den erişilen modellerin çoğu kapalı yapay zekâ modelleri sınıfına girer.

AI API Kullanmak İçin Gerekenler

Yola çıkmak için gereken liste kısadır:

1. Sağlayıcı hesabı: Kullanacağınız modelin resmî geliştirici platformunda bir hesap açarsınız.
2. API anahtarı: Hesap panelinden oluşturduğunuz, sizi tanıtan uzun ve gizli bir dizgidir; her istekle birlikte gönderilir.
3. Bir istemci: İsteği göndermek için Python gibi bir programlama dili, curl komutu veya Postman gibi görsel bir araç kullanabilirsiniz. Yani ilk deneme için profesyonel bir programcı olmanız gerekmez.
4. Kredi ya da kota: Çoğu sağlayıcı kullanım başına ücret alır; yeni hesaplara genellikle küçük bir deneme kredisi tanımlanır.

İlk İsteği Göndermek: Kalıp ve Parametreler

Farklı sağlayıcıların API'leri ayrıntıda farklılaşsa da hepsi aynı kalıbı izler: hangi modeli istediğinizi ve ona ne söyleyeceğinizi bildirirsiniz, yanıt JSON biçiminde döner. Bir istek gövdesinde en sık göreceğiniz alanlar şunlardır:

• model: kullanacağınız modelin adı; örneğin gpt-4o gibi bir tanımlayıcı.
• messages: konuşmanın içeriği; her ileti bir rol ve bir metin taşır.
• temperature: yaratıcılık ayarı; düşük değerler tutarlı ve öngörülebilir, yüksek değerler çeşitli ve beklenmedik yanıtlar üretir.
• max_tokens: yanıt uzunluğu için üst sınır; maliyeti kontrol etmenin basit yoludur.

Somut bir istek gövdesi şöyle görünür; aynı gövdeyi curl ile şöyle gönderirsiniz:

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{ "model": "gpt-4o", "temperature": 0.3, "max_tokens": 200,
    "messages": [
      { "role": "system", "content": "Sen kısa yanıt veren bir teknik destek asistanısın." },
      { "role": "user", "content": "API anahtarı neden gizli tutulmalıdır?" }
    ] }'

Sunucudan dönen yanıt da JSON biçimindedir; modelin ürettiği metin choices[0].message.content alanında, faturalamada sayılan tokenlar ise usage bloğundadır:

{
  "id": "chatcmpl-8xKq2", "model": "gpt-4o",
  "choices": [
    { "message": { "role": "assistant", "content": "API anahtarı, isteğin sizin adınıza ve hesabınıza yapıldığını kanıtlar; gizli tutulmazsa başkaları sizin adınıza ücretli istek gönderebilir." }, "finish_reason": "stop" }
  ],
  "usage": { "prompt_tokens": 41, "completion_tokens": 28, "total_tokens": 69 }
}

messages listesindeki roller modelin davranışını şekillendirir. system, modelin karakterini ve kurallarını belirleyen talimattır (örneğin: sen bir teknik destek asistanısın, kısa yanıt ver) ve kullanıcıya gösterilmez. user kullanıcının gerçek sorusudur; assistant ise modelin önceki yanıtlarıdır. Model kendisi hiçbir şeyi hatırlamaz; çok turlu bir sohbette geçmişi hatırlıyor gibi görünmesinin nedeni, uygulamanın tüm önceki iletileri her istekte yeniden göndermesidir. Kod tarafında ilerlemek isterseniz AI ile kod yazma dersimizdeki örneklerle bu kalıbı birleştirebilirsiniz.

Token, Kota ve Maliyet Mantığı

AI API'lerinde hem faturalama hem de limitler token üzerinden işler. Token kabaca kelime parçası demektir; bir Türkçe kelime ortalama birkaç token eder. Ücret iki kalemdir: istekle gönderdiğiniz girdi tokenları ve modelin ürettiği çıktı tokenları. Sağlayıcılar ayrıca hız limiti (rate limit) uygular: dakikada en fazla şu kadar istek, şu kadar token gibi. Sınıra takılırsanız istek kısa süreliğine reddedilir; hata kodu genellikle 429'dur ve çözümü bekleyip yeniden denemektir. Ücretsiz ilerleme yolları ise şunlardır: deneme kredisi veren bulut platformları, geliştirme sırasında ücretsiz katman sunan bazı sağlayıcılar ve açık kaynak yapay zekâ modelleri dersinde anlatılan modelleri kendi makinenizde çalıştırmak.

Sık Yapılan Hatalar ve Yanılgılar

Yeni başlayanların en çok takıldığı noktalar şunlardır:

• Anahtarı kodun içine yazıp depoya yüklemek: Kod paylaşım sitelerine sızan anahtarlar dakikalar içinde bulunur ve sizin adınıza istek atılıp fatura çıkarabilir. Anahtarı ortam değişkeninde (environment variable) saklayın; yanlışlıkla açığa çıktıysa hemen iptal edin.
• Sohbet aboneliğinin API'yi de kapsadığını sanmak: Çoğu sağlayıcıda ikisi ayrıdır; sohbet uygulaması aboneliği API kullanımını ödemez.
• Geçmişi göndermeyi unutmak: Model önceki turları bilmez; kullanıcının sohbetin unuttuğundan şikâyet etmesinin klasik nedeni, uygulamanın geçmişi isteğe eklemeyi atlamasıdır.
• Her görevde yüksek temperature kullanmak: Kod üretimi veya matematik gibi kesinlik isteyen işlerde yüksek sıcaklık hata oranı artırır; düşük değer tercih edin.
• API yanıtını doğrulamadan kabul etmek: API'den gelen yanıtlar da hâlâ yanılabilir; kritik iş akışlarında çıktıyı denetleyen bir katman kurun.
• Hata mesajlarını okumamak: 401 anahtar ya da kimlik sorunu, 429 hız limiti, 500 sağlayıcı tarafı hatası demektir; her hataya aynı tepkiyi vermek sorunu çözmez.

Kısacası API kullanımı teknikten çok disiplin işidir: anahtarı koruyun, geçmişi yönetin, çıktıyı denetleyin.

Ötesi: API Üzerine Uygulama Kurmak

Tek bir istek göndermeyi öğrendikten sonra gerçek proje, bu kalıbı büyütmektir. Bir müşteri destek botu, kullanıcının sorusunu alır, system talimatıyla birlikte API'ye iletir ve yanıtı kullanıcıya gösterir. Şirketinizin kendi belgelerinden beslenen bir asistan istiyorsanız RAG nedir? dersimiz tam bu noktaya girer; modeli belirli bir göreve uyarlamak için Fine-tuning nedir? dersine bakabilirsiniz. Modelin araç kullanıp kendi başına adım attığı sistemler kurmak isterseniz AI agent nedir? ve AI agent nasıl çalışır? derslerimiz yola çıkış noktanız olsun. Hangi modeli seçeceğinizden emin değilseniz Yapay zekâ modeli karşılaştırma rehberimiz işinizi kolaylaştırır.