Claude API'yi Uygulamanıza Nasıl Entegre Edersiniz

Claude API'yi entegre etmek için Anthropic'in Claude Console'unda bir API anahtarı oluşturun, bunu bir sunucu tarafı gizli değer olarak saklayın (genellikle ANTHROPIC_API_KEY) ve Anthropic'in resmi SDK'larından birini kullanarak kendi sunucunuzdaki bir rotadan Messages API'yi çağırın. Her istek bir model adı verir, max_tokens (kabul edeceğiniz en uzun yanıtı) belirler ve konuşmayı messages olarak gönderir; talimatlarınız ise ayrı bir system istemi içinde yer alır. Bir harcama limiti belirleyin, uzun yanıtları akış (stream) ile gönderin ve hız sınırı (429) ile aşırı yük (529) hatalarını yeniden denemelerle yönetin.

Bu rehber kurulumu, güvenli bir istek akışını, bir AI oluşturucu için istemleri ve dikkat edilmesi gereken hataları kapsar. Anthropic ayrıntıları, Eylül 2026 itibarıyla kendi dokümantasyonundan alınmıştır. Token ve fiyatlandırmanın genel işleyişi için LLM API'leri nasıl kullanılır bölümüne bakın.

Bununla neler yapabilirsiniz?

• Sohbet asistanları ve yardım pencereleri (AI sohbet robotu uygulaması nasıl yapılır)
• Özetler, yeniden yazımlar ve taslak yanıtlar
• Belgelerden, e-postalardan ve formlardan alan çıkarma
• Kendi içeriğinizden soruları yanıtlama
• Tool use ile uygulamanızın fonksiyonlarını çağıran agent'lar

Daha fazla fikir için uygulamanıza AI özellikleri nasıl eklenir bölümüne bakın.

Messages API'ye kısa bakış

Anthropic'in API referansına göre bir istek, şunlarla birlikte https://api.anthropic.com/v1/messages adresine bir POST isteğidir:

API durumsuzdur: bir konuşmaya devam etmek için her istekte önceki turları yeniden göndermeniz gerekir. Uzun sohbetlerin mesaj başına neden daha pahalı olduğu da budur.

Anthropic, Python, TypeScript, C#, Go, Java, PHP ve Ruby için resmi SDK'lar yayınlar. Bunlar başlıkları ayarlar, yanıtları ayrıştırır ve akışı destekler. Bunun bir nedeni yoksa ham HTTP yerine bunlardan birini kullanın.

Model seçimi

Anthropic, yetenek ile hız ve fiyat arasında denge kuran birkaç Claude modeli sunar ve bu seçenekler değişir. Görevinizi iyi yapan en küçük modeli seçin, gerçek örneklerle test edin ve model kimliğini yapılandırmada tutun; böylece kodu değiştirmeden geçiş yapabilirsiniz. Güncel seçenekler ve oranlar için Anthropic'in model ve fiyatlandırma sayfalarını kontrol edin.

Hesabınızı kurmak

1. platform.claude.com adresinde Claude Console'a giriş yapın ve faturalandırma ekleyin.
2. Bir API anahtarı oluşturun. Her ortam (test ve üretim) için bir anahtar tutun; böylece birini iptal ederken diğerini bozmazsınız.
3. Bir harcama limiti belirleyin. Anthropic'in hata sayfası, kullanımın belirlediğiniz harcama limitine ulaşması durumunda API'nin 400 hatası döndürdüğünü belirtir; bu yüzden uygulamanız bu durumda açık bir mesaj göstermelidir.
4. Konsol'da hesabınız için hız sınırlarını inceleyin; bunlar organizasyon bazında ölçülür.

İstek akışı

1. Kullanıcı uygulamanızda bir işlem yapar: mesaj gönderir, "Özetle" düğmesine tıklar.
2. Tarayıcı Anthropic'i doğrudan değil, sizin sunucu rotanızı çağırır.
3. Sunucunuz kullanıcının giriş yapmış ve bu özelliği kullanmaya yetkili olduğunu kontrol eder ve kullanıcı başına bir limit uygular.
4. İsteği oluşturur: kurallarınızı içeren bir sistem istemi, kullanıcının girdisi ve görev için veritabanınızdan gereken veriler.
5. Ortamdan alınan anahtarla ve makul bir max_tokens değeriyle Messages API'yi çağırır.
6. Yanıtı tarayıcıya akıtır ve yanıttan token kullanımını kaydeder.

Seçenekler ve ödünleşimler

AI oluşturucunuza verilecek istemler

İlk bir özellik:

"Bu belgeye dair sor" paneli ekle. Kullanıcının giriş yapmış olduğunu ve belgenin sahibi olduğunu kontrol eden bir sunucu rotası POST /api/ask çağırsın; ardından resmi Anthropic SDK'sı ve ANTHROPIC_API_KEY gizli değeriyle Claude Messages API'sini çağırsın. Model kimliğini CLAUDE_MODEL gizli değerinden okusun. Sistem istemi: "Yalnızca sağlanan belgeden yanıtla. Yanıt orada yoksa bunu söyle." Belge metnini ve soruyu gönder, max_tokens değerini 800 yap, yanıtı sayfaya akıt ve anahtarı asla tarayıcıya açma.

Korumalar ve hatalar:

Her kullanıcıyı saatte 20 soruyla sınırla; bu veritabanında takip edilsin. Her yanıttan giriş ve çıkış token'larını, kullanıcı kimliği ve istek kimliği ile kaydet. 429 veya 529 hatalarında, retry-after başlığına uyarak en fazla 3 kez üstel geri çekilme ile yeniden dene, ardından "Asistan şu anda meşgul, lütfen biraz sonra tekrar deneyin." göster. API bir harcama limiti hatası bildirirse "AI özellikleri duraklatıldı" göster ve yöneticiyi uyar.

Dikkat edilmesi gereken hatalar

Anthropic'in hata dokümantasyonuna göre, uygulamanızın gerçekten karşılayacağı hatalar:

Anthropic'in dokümanlarına göre resmi SDK'lar, geçici hataları (bağlantı hataları, hız sınırları ve 5xx hataları) varsayılan olarak üstel geri çekilme ile iki kez otomatik olarak yeniden dener ve bunu yapılandırabilirsiniz. Her yanıt bir request-id başlığı taşır; destek ekibinin sorunları izleyebilmesi için bunu kaydedin.

Sık yapılan hatalar

• API'yi tarayıcıdan çağırmak. Anahtarınız herkese açık hale gelir. Her zaman sunucunuz üzerinden gidin. Bkz. API anahtarlarını güvende tutma.
• max_tokens'ın bir hedef değil, bir üst sınır olduğunu unutmak. Özelliğin ihtiyacı olan değere ayarlayın; çok düşük olursa yanıtlar kesilir, çok yüksek olursa uzun ve pahalı yanıtlar riski doğar.
• Kuralları kullanıcı mesajına koymak. Sabit talimatlar system istemine ait; izinler ise kodunuzda olmalıdır.
• Tüm sohbeti sonsuza kadar göndermek. Konuşmalar büyüdükçe eski turları kırpın veya özetleyin.
• Harcama limiti veya kullanıcı başına sınır koymamak.
• Model kimliğini kodda sabitlemek. Modeller güncellenir ve emekli edilir.
• Durma nedenini yok saymak. Yanıt max_tokens değerine ulaştığı için durduysa, kullanıcıya söyleyin ya da üst sınırı yükseltin.

Kontrol listesi

• API anahtarı Claude Console'da oluşturuldu ve sunucu tarafı gizli değer olarak saklandı
• Test ve üretim için ayrı anahtarlar
• Harcama limiti ayarlandı; limite ulaşıldığında net bir mesaj gösteriliyor
• Tüm istekler izin kontrolleri yapan sunucunuz üzerinden gidiyor
• Sistem istemi kuralları tutuyor; model kimliği yapılandırılabilir
• max_tokens özellik başına ayarlandı; uzun yanıtlar akıtılıyor
• Uygulamanızda kullanıcı başına hız sınırı var
• 429 ve 529 geri çekilme ile işleniyor; istek kimlikleri kaydediliyor
• Sayfayı bozmayan, anlaşılır bir hata durumu var
• Boş, çok uzun ve kötü niyetli girdilerle test edildi

Mythex'te Claude API kullanımı

Mythex üzerinde oluşturduğunuz uygulamalarda Claude özellikleri kendi Anthropic anahtarınızı kullanır ve Mythex oluşturma kredileri yerine Anthropic hesabınıza faturalandırılır. Bu, kodunuzu yazan Mythex agent'ından ayrıdır. ANTHROPIC_API_KEY değerini /secrets, proje ayarları veya sohbetteki gizli değerler kartı üzerinden bir proje gizli değeri olarak ekleyin, ardından yukarıdakine benzer istemleri kullanarak özelliği tarif edin. Canlı bir uygulamada gizli değerleri değiştirdikten sonra yeniden yayınlayın. Başlangıç istemi için Kendi API anahtarlarınızla AI özellikleri ekleyin bölümüne bakın. Sağlayıcılar arasında seçim yapıyorsanız, OpenAI API'si nasıl entegre edilir aynı konuyu OpenAI için ele alır.

Sorular