Claude API’ye giriş: anahtar, model seçimi ve araç kullanımı

Bu derste Claude API için Console’dan anahtar almayı, ilk isteği göndermeyi, işinize uygun modeli nasıl seçeceğinizi, maliyetin nasıl oluştuğunu ve araç kullanımının (tool use) temellerini öğreneceksiniz. Sohbet ekranındaki Claude’un arkasındaki bu kapıyı kendi uygulamanızdan açacaksınız.

Not: Claude API kullanımı ücretlidir. Hesabı Claude Console’da açarsınız; Anthropic’in belgesine göre kredi Console’un faturalandırma ayarlarından satın alınır ve ücret kullanıma göre belirlenir. Aynı belge yeni kullanıcılara test için küçük bir ücretsiz kredi verildiğini söylüyor.

Aklınıza bir soru mu takıldı?

Sorunuzu ya da aradığınız konuyu yazın Ders bul

Bu derste neler öğreneceksiniz?

• API anahtarını güvenle almayı, saklamayı ve ilk isteği göndermeyi.
• Model seçerken hangi ölçülere bakacağınızı ve maliyetin neden oluştuğunu.
• Araç kullanımının adımlarını ve bir araç tanımının nasıl yazıldığını.

API anahtarı almak

Başlangıç sayfasına göre ilk adım bir Claude Console hesabı açmaktır. Anahtarı Console’un anahtarlar sayfasından oluşturursunuz. SDK’lar ve komut satırı aracı anahtarı ANTHROPIC_API_KEY adlı ortam değişkeninden okur. Ortam değişkeni, bilgisayarın uygulamalara verdiği gizli bir ayardır; anahtarı kodunuzun içine yazmanız gerekmez. Sayfadaki macOS ve Linux örneği:

export ANTHROPIC_API_KEY="your-api-key-here"

Aynı sayfa yerel geliştirme için, anahtar yerine ant auth login komutuyla komut satırı aracından giriş yapmayı öneriyor; giriş bittikten sonra SDK’lar kimlik bilgilerini kendiliğinden bulur. Windows’ta ortam değişkenini tanımlama adımı bu sayfada yok; bunu Claude Code’a yaptırabilir ya da Windows ayarlarından ekleyebilirsiniz.

Güvenlik: API anahtarı parola gibidir; onu bilen herkes sizin hesabınızdan harcama yapabilir. Anahtarı sohbete, e-postaya, ekran görüntüsüne, GitHub’a ya da bir web sitesinin herkese açık koduna koymayın. Sızdığından şüphelenirseniz Console’dan yeni bir anahtar oluşturup eskisini kullanmayı bırakın.

İlk istek

Sayfa Python örneğini şöyle veriyor. Önce sanal ortam ve SDK kurulur (macOS ve Linux komutları):

python3 -m venv .venv && source .venv/bin/activate
pip install anthropic

Sonra quickstart.py dosyası oluşturulur. Aşağıdaki sürüm belgedeki örneğe dayanır; model adı bugün kontrol edilen resmî modeller sayfasından alınmıştır, siz kendi çalışmanızda sayfadaki güncel adı kullanın:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[
        {
            "role": "user",
            "content": "Bir esnaf için kısa bir indirim duyurusu yaz.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Çalıştırmak için python quickstart.py yazmanız yeterli. max_tokens yanıtın uzunluğuna üst sınır koyar; yanıttaki usage alanı kaç giriş ve çıkış token’ı kullandığınızı gösterir.

Model nasıl seçilir?

Anthropic’in modeller sayfası sürümleri sürekli güncelliyor; bu yüzden ders model adı ezberletmiyor. Bunun yerine sayfanın verdiği ölçüleri kullanın:

• Varsayılan: Sayfa, çoğu iş için önerdiği modelle başlamayı söylüyor. Önce onu deneyin.
• Zor işler: Derin muhakeme ya da uzun süren ajan işleri için en yetenekli kademe öneriliyor; özellikle varsayılan model sizin kendi sınamalarınızda yetersiz kalırsa.
• Yüksek hacim: Sınıflandırma, bilgi ayıklama ve yönlendirme gibi çok sayıda hızlı iş için en küçük ve en hızlı kademe uygun görülüyor.
• Denge: Yetenek arttıkça gecikme ve fiyat da artıyor. Orta kademe hız ile zekâ arasındaki dengeyi kuruyor.

Pratik yöntem şudur: kendi işinizden birkaç gerçek örnek seçin, aynı örnekleri iki kademede deneyin ve yeterli olan en hafif kademeyi kullanın. Ayrıca her modelin bir yaşam döngüsü durumu vardır: etkin, kullanımdan kaldırılmış ya da emekliye ayrılmış. Kullanımdan kaldırılan model yeni kullanıcılara kapanır, emekli model ise istekleri başarısız kılar. Kullandığınız modelin durumunu sayfadan arada bir kontrol edin.

Maliyet ve araç kullanımı

Fiyatlandırma sayfasına göre ücret esas olarak giriş ve çıkış token’larına bağlıdır; token, metnin modelin işlediği küçük parçasıdır. Her modelin kendi oranı vardır; güncel oranlar için fiyat sayfasına bakın, derste rakam verilmedi. Maliyeti etkileyen başlıca etkenler:

• Uzun komut ve uzun yanıt daha çok token demektir.
• Araç tanımları, araç çağrıları ve sonuçları da giriş token’ı sayılır.
• Web araması gibi bazı sunucu araçları ayrıca kullanım başına ücretlendirilir.
• Komut önbelleği (prompt caching) tekrar kullanılan bölümleri ucuza okutur; toplu işlem (Batch API) acelesi olmayan işlerde indirim sağlar.

Araç kullanımı, Claude’un sizin tanımladığınız işlevleri çağırmasına izin verir. Belgeye göre akış beş adımdır:

1. İsteğinizi tools tanımlarıyla gönderirsiniz.
2. Claude, stop_reason değeri tool_use olan ve araç adı, kimlik ve girdiyi içeren bir yanıt döndürür.
3. Sizin kodunuz aracı çalıştırır. Claude işlevi kendisi çalıştırmaz.
4. İkinci istekte, aracın sonucunu tool_result bloğuyla geri gönderirsiniz.
5. Claude sonucu kullanarak nihai yanıtı yazar.

Araç tanımı üç alandan oluşur: name (ad), description (ne işe yaradığı; Claude ne zaman çağıracağına buna bakarak karar verir) ve input_schema (girdinin biçimini anlatan JSON şeması). Aşağıdaki tanım yalnızca alanları göstermek için yazılmış bir örnektir:

tools = [
    {
        "name": "kargo_durumu_sorgula",
        "description": "Takip numarası verilen kargonun durumunu döndürür.",
        "input_schema": {
            "type": "object",
            "properties": {
                "takip_no": {
                    "type": "string",
                    "description": "Kargo takip numarası",
                }
            },
            "required": ["takip_no"],
        },
    }
]

Belge ayrıca Claude’un araç çağırma davranışının garanti edilmediğini, özellikle belirsiz isteklerde zorunlu bir parametrenin eksik gelebileceğini söylüyor. Tanıma strict: true eklemek çağrıların şemaya tam uymasını sağlar; bir aracın mutlaka çağrılması için de tool_choice kullanılır.

Adım adım uygulama

1. Claude Console’da hesap açın ve faturalandırmayı kontrol edin.
2. Bir API anahtarı oluşturun; yalnızca parola yöneticinize kaydedin.
3. Anahtarı ortam değişkeni olarak tanımlayın ya da ant auth login ile giriş yapın.
4. Sanal ortamı kurup SDK’yı yükleyin.
5. İlk isteği gönderin ve yanıttaki usage alanına bakın.
6. İşinizden iki gerçek örnekle iki farklı kademeyi deneyin.
7. Küçük bir araç tanımı ekleyin; yanıtta tool_use gelip gelmediğini kontrol edin.

Kontrol listesi

• Anahtar kodda, sohbette ve ekran görüntüsünde yok.
• Anahtarı ortam değişkeninden okuyorum.
• Model adını resmî sayfadan kontrol ettim.
• Maliyeti usage alanından izliyorum.
• Araç çıktısını kullanmadan önce kendi kodumda doğruluyorum.

Sık yapılan hatalar

• Anahtarı koda gömmek: Kod bir yere yüklendiğinde anahtar da yayılır. Ortam değişkeni kullanın.
• Model adını eski bir yazıdan kopyalamak: Adı ve durumunu her zaman resmî modeller sayfasından doğrulayın.
• Her işte en büyük modeli seçmek: Gecikme ve fiyat yetenekle birlikte artar. Önce kendi örneklerinizle ölçün.
• Araç sonucuna körü körüne güvenmek: Claude’un ürettiği girdiyi çalıştırmadan önce doğrulayın; silme ya da para gönderme gibi geri alınamayan işleri araca onaysız vermeyin.
• Kişisel veriyi düşünmeden göndermek: API’ye gönderdiğiniz metinde müşteri verisi varsa KVKK yükümlülüklerinizi önceden değerlendirin.

Kendinizi deneyin

Kaynaklar

• Get started with the Claude API – Claude Platform Docs (İngilizce)
• Models overview – Claude Platform Docs (İngilizce)
• Tool use with Claude – Claude Platform Docs (İngilizce)
• Pricing – Claude Platform Docs (İngilizce)

Son kontrol: 7 Kasım 2026

Kaynak: yzdersleri.com/ders/claude-api-giris/ · Yapay Zeka Dersleri