Claude API PHP Entegrasyonu Nasıl Yapılır?

Son güncelleme

Claude API’yi PHP ile kullanmak, uygulamanızın sunucu tarafından Anthropic’in Messages API’sine HTTP isteği göndermesi ve dönen yanıtı işlemesi demektir. Müşteri destek asistanı, içerik özetleme, form verisinden yapılandırılmış bilgi çıkarma veya kod açıklama gibi işler bu yapıyla birkaç saatte prototiplenebilir. Ancak canlı bir sistemde API anahtarının güvenli saklanması, model kimliğinin güncel tutulması, hata kodlarının doğru ele alınması, maliyetin izlenmesi ve model çıktısının güvenle gösterilmesi gibi konular baştan tasarlanmalıdır. API anahtarı tarayıcıya veya Git deposuna konmamalı; model kimliği ve desteklenen parametreler her zaman resmi API belgelerinden güncel olarak seçilmelidir. Bu rehberde cURL ile ilk istekten servis sınıfına, hata yönetiminden prompt önbelleğine kadar PHP projelerinde Claude API entegrasyonunu adım adım ele alıyoruz.

Hazırlık: anahtar, model ve ortam

Claude API anahtarını sunucuda saklayıp PHP ile güvenli istek oluşturma
Anahtarı yalnızca sunucu tarafında saklayın.

Claude API’yi kullanmak için Anthropic Console üzerinden bir API anahtarı oluşturmanız gerekir. Anahtar, hesabınıza bağlı kullanım ve faturalandırmayı temsil eder; ele geçirilmesi başkalarının sizin adınıza istek göndermesi anlamına gelir.

  • Anahtarı ortam değişkeninde tutun: .env dosyasında veya sunucu yapılandırmasında saklayın; .env dosyasının Git’e eklenmediğinden ve web kök dizininden erişilemediğinden emin olun.
  • Ortamlara ayrı anahtar: Geliştirme ve canlı ortam için ayrı anahtarlar kullanmak, bir anahtarın sızması durumunda etkiyi sınırlar ve kullanım raporlarını ayırır.
  • Harcama sınırı: Console’da kullanım ve harcama sınırları tanımlayarak beklenmedik maliyetlere karşı önlem alın.
  • Model adını yapılandırmada tutun: Model kimliklerini koda gömmeyin. Yeni model sürümleri çıktıkça veya eski sürümler emekliye ayrıldıkça tek bir ayarla geçiş yapabilmek için model adını ortam değişkeninden okuyun.
  • PHP gereksinimleri: cURL eklentisi ve dışarıya HTTPS bağlantısı yapabilen bir sunucu yeterlidir. Composer kullanıyorsanız Guzzle gibi bir HTTP istemcisi kodu sadeleştirir.

İstek yapısı

Messages API’ye /v1/messages uç noktasına POST isteği gönderilir. İstekte üç başlık zorunludur: API anahtarını taşıyan x-api-key, API sürümünü belirten anthropic-version ve content-type: application/json. İstek gövdesinin temel alanları şunlardır:

  • model: Kullanılacak model kimliği.
  • max_tokens: Yanıtın en fazla kaç token olabileceği. Zorunlu bir alandır ve maliyet kontrolünün ilk aracıdır.
  • system: Modelin rolünü, üslubunu ve kurallarını belirleyen sistem talimatı. Mesaj dizisinin dışında, ayrı bir alan olarak gönderilir.
  • messages: user ve assistant rollerinin sırayla yer aldığı konuşma dizisi.
  • temperature: Yanıtın ne kadar değişken olacağını belirler; sınıflandırma ve veri çıkarma gibi işlerde düşük değerler daha tutarlı sonuç verir.

cURL ile ilk istek

<?php
function claudeSor(string $soru): array
{
    $govde = [
        'model'      => getenv('CLAUDE_MODEL'),
        'max_tokens' => 1024,
        'system'     => 'Türkçe, kısa ve teknik olarak doğru yanıt ver.',
        'messages'   => [
            ['role' => 'user', 'content' => $soru],
        ],
    ];

    $ch = curl_init('https://api.anthropic.com/v1/messages');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'x-api-key: ' . getenv('ANTHROPIC_API_KEY'),
            'anthropic-version: 2023-06-01',
            'content-type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode($govde, JSON_UNESCAPED_UNICODE),
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT        => 90,
    ]);
    $ham   = curl_exec($ch);
    $durum = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $hata  = curl_error($ch);
    curl_close($ch);

    if ($ham === false) {
        throw new RuntimeException("Bağlantı hatası: $hata");
    }
    return ['durum' => $durum, 'veri' => json_decode($ham, true)];
}

anthropic-version başlığının değerini ve kullanılabilir model kimliklerini resmi belgeden kontrol edin. Bağlantı zaman aşımını kısa, toplam zaman aşımını ise beklediğiniz en uzun yanıt süresine göre belirleyin; uzun yanıtlarda kullanıcının beklememesi için akış (streaming) yöntemini değerlendirin.

Yanıtı ayrıştırmak

Başarılı bir yanıtta üretilen içerik content dizisinde bloklar halinde gelir. Metin yanıtları type değeri text olan bloklardadır; araç kullanımı gibi özelliklerde farklı blok türleri de bulunabilir. Bu nedenle yalnızca ilk bloğu okumak yerine tüm metin bloklarını birleştirin:

$sonuc = claudeSor($soru);
$veri  = $sonuc['veri'];

if ($sonuc['durum'] !== 200) {
    $tur   = $veri['error']['type'] ?? 'bilinmeyen';
    $mesaj = $veri['error']['message'] ?? '';
    // hata türüne göre ele al
}

$metin = '';
foreach ($veri['content'] ?? [] as $blok) {
    if (($blok['type'] ?? '') === 'text') {
        $metin .= $blok['text'];
    }
}

$durmaNedeni = $veri['stop_reason'] ?? null;   // end_turn, max_tokens ...
$girdiToken  = $veri['usage']['input_tokens'] ?? 0;
$ciktiToken  = $veri['usage']['output_tokens'] ?? 0;

stop_reason değeri end_turn ise yanıt doğal olarak tamamlanmıştır. max_tokens ise yanıt sınıra ulaşıp kesilmiştir; kesik bir yanıtı tamamlanmış gibi kullanıcıya göstermeyin veya veritabanına kaydetmeyin. usage alanındaki token sayılarını her istek için kaydetmek, maliyet takibinin temelidir.

Hata yönetimi

Claude API yanıtında başarı, oran sınırı ve sunucu hatasını ayrı yönetme
Yanıtın hem HTTP durumunu hem bitiş nedenini değerlendirin.

API, hata durumunda HTTP durum kodu ile birlikte error nesnesi içinde hata türü ve açıklama döndürür. Her hatayı aynı şekilde tekrar denemek hem maliyeti artırır hem de sorunu gizler:

  • 400 (invalid_request_error): İstek gövdesi hatalı; eksik max_tokens, yanlış rol sırası veya geçersiz parametre. Tekrar denemek işe yaramaz, isteği düzeltin.
  • 401 (authentication_error): API anahtarı geçersiz veya eksik.
  • 403 (permission_error): Anahtarın bu kaynağa veya modele erişim izni yok.
  • 404 (not_found_error): Model kimliği yanlış veya artık kullanılmıyor.
  • 413 (request_too_large): İstek boyutu sınırı aşıldı; uzun belgeleri parçalayın.
  • 429 (rate_limit_error): Oran sınırı aşıldı. Yanıttaki retry-after başlığına uyarak bekleyin ve artan bekleme süreleriyle sınırlı tekrar deneyin.
  • 500 ve 529 (api_error, overloaded_error): Sağlayıcı tarafında geçici sorun veya yoğunluk. Sınırlı sayıda, artan beklemeli tekrar deneme uygundur.

Oran sınırı hatalarının ayrıntılı teşhisi için Anthropic API 429 rehberimize göz atabilirsiniz. Tekrar denemelerde aynı kullanıcı işleminin iki kez kaydedilmemesi için yazma adımını yalnızca başarılı ve tamamlanmış yanıttan sonra yapın.

Kodu bir servis sınıfında toplamak

API çağrılarını controller’lara dağıtmak yerine tek bir servis sınıfında toplamak bakım ve testi kolaylaştırır. Servis sınıfı model adını, zaman aşımını, tekrar deneme kurallarını ve kayıt tutmayı tek yerden yönetir. Laravel kullanıyorsanız Http::withHeaders([...])->timeout(90)->retry(3, 1000)->post(...) zinciri, tekrar deneme mantığını kısa yoldan sağlar; ancak retry fonksiyonunu yalnızca 429 ve 5xx gibi tekrar denemeye uygun hatalar için çalışacak şekilde koşullandırın.

Servis sınıfının dönen değeri “metin”, “kesildi mi”, “kaç token harcandı” ve “hangi model kullanıldı” gibi bilgileri açıkça taşıyan küçük bir nesne olmalıdır. Testlerde bu sınıfın yerine sahte bir sınıf koyarak gerçek API’ye istek göndermeden uygulamanızı test edebilirsiniz.

Çok turlu sohbet

Messages API durumsuzdur; önceki mesajlar her istekte yeniden gönderilir. Sohbet geçmişini kullanıcı kimliğiyle ilişkili olarak sunucuda saklayın. API, art arda gelen aynı rollü mesajları tek tura birleştirebilir; bu nedenle geçmişin gerçekten beklediğiniz konuşma sırasını yansıttığını kontrol edin. Kullanıcı istemcisinden gelen “assistant” mesajlarını doğrulamadan geçmişe eklemeyin. Sohbet uzadığında eski turları özetleyin veya seçerek gönderin; bunu yaparken kullanıcı açısından önemli kısıtları kaybetmeyin.

Sohbet geçmişini her zaman sunucuda, kullanıcı kimliğiyle ilişkilendirerek saklayın. Geçmişi istemciden gelen bir diziye güvenerek oluşturmak, kullanıcının sahte “assistant” mesajları ekleyerek modeli yönlendirmesine kapı açar.

Maliyet ve performans

  • Doğru model: Basit sınıflandırma, özetleme veya veri çıkarma için daha küçük ve hızlı modeller genellikle yeterlidir; karmaşık akıl yürütme gerektiren işlerde daha güçlü modelleri tercih edin.
  • Prompt önbelleği: Her istekte tekrar eden uzun sistem talimatları veya belgeler için prompt caching özelliği, önbelleğe alınan kısmın tekrar işlenmesini ve maliyetini önemli ölçüde azaltabilir. Hangi içeriklerin önbelleğe alınabileceğini ve süre sınırlarını belgeden kontrol edin.
  • Çıktı sınırı: max_tokens değerini görevin gerektirdiği kadar tutun.
  • Toplu işler: Anlık yanıt gerektirmeyen büyük işler için toplu işlem (batch) API’si daha düşük maliyetle sonuç verebilir.
  • Kuyruk: Uzun süren işleri kullanıcı isteğinden ayırıp kuyrukta çalıştırın.

Token maliyetini azaltma yöntemlerinin ayrıntıları için AI API token maliyeti rehberimize bakabilirsiniz.

Güvenlik ve kullanıcı verisi

  • Model yanıtını ekrana basarken htmlspecialchars() ile kaçış uygulayın; Markdown kullanıyorsanız güvenli bir dönüştürücü ve HTML temizleyici kullanın.
  • Kullanıcı başına istek sayısı ve mesaj uzunluğu sınırı koyun.
  • Kişisel verileri API’ye göndermeden önce gerekliliğini değerlendirin ve gizlilik politikanızda belirtin.
  • Model yanıtına dayanarak ödeme, silme veya e-posta gönderme gibi işlemleri onay almadan otomatik yapmayın; araç kullanımı için function calling rehberimizdeki güvenlik ilkelerini uygulayın.
  • Kullanıcıdan veya dış kaynaklardan gelen metinlerin sistem talimatınızı geçersiz kılmaya çalışabileceğini unutmayın.

Yapılandırılmış çıktı ve veri çıkarma

Claude API’yi serbest metin üretmenin yanı sıra yapılandırılmış veri çıkarmak için de kullanabilirsiniz: müşteri e-postasından talep türünü ve sipariş numarasını çıkarmak, ürün açıklamasından teknik özellikleri tabloya dökmek veya yorumları duygu kategorilerine ayırmak gibi. Bu tür işlerde güvenilir sonuç almak için:

  • Sistem talimatında beklenen JSON yapısını alan adları ve izin verilen değerlerle açıkça tanımlayın.
  • Mümkünse araç tanımı (tool) ile bir giriş şeması vererek modelin yanıtı bu şemaya uygun üretmesini sağlayın; bu yöntem serbest metinden JSON ayıklamaya göre daha tutarlıdır.
  • Dönen JSON’u json_decode ile ayrıştırdıktan sonra zorunlu alanları, veri türlerini ve izin verilen değerleri kendi doğrulama kurallarınızla kontrol edin.
  • Model bilgiyi bulamadığında alanları boş bırakmasını açıkça isteyin; aksi halde tahmin üretebilir.
  • temperature değerini düşük tutun.

Şemaya uygun bir JSON, içeriğin doğru olduğu anlamına gelmez. Özellikle fiyat, tarih ve kimlik numarası gibi kritik alanları uygulama tarafında ayrıca doğrulayın.

Laravel ile örnek servis kullanımı

Laravel projelerinde Claude çağrısını bir servis sınıfına alıp controller’dan kullanmak kodu sade tutar. Servis sınıfını AppServiceProvider içinde yapılandırma değerleriyle kaydedin, controller’a bağımlılık olarak enjekte edin ve uzun işleri kuyruk işine taşıyın. Kullanıcıya hızlı geri bildirim vermek gereken sohbet arayüzlerinde ise akış (streaming) yöntemini kullanarak yanıtın parça parça görünmesini sağlayabilirsiniz; ayrıntılar Streaming API rehberimizde. Her iki durumda da kullanıcı başına oran sınırı uygulamak için Laravel’in RateLimiter yapısından yararlanın.

Sıkça Sorulan Sorular

Claude API için PHP SDK’sı var mı?

Evet. Anthropic’in PHP için resmî SDK belgesi bulunuyor; güncel kurulum ve desteklenen özellikleri bu belgeden kontrol edin. Bağımlılığı sınırlamak istiyorsanız Messages API’yi cURL veya güvenilir bir HTTP istemcisiyle çağırabilirsiniz. İki yöntemde de anahtar, zaman aşımı ve hata yönetimi sunucuda kalmalıdır.

“model not found” hatası alıyorum, neden?

Model kimliği yanlış yazılmış, artık desteklenmiyor veya hesabınızın erişimi yok olabilir. Belgedeki güncel model listesini kontrol edin ve model adını yapılandırmadan okuyun.

Yanıtlar neden yarıda kesiliyor?

stop_reason değeri max_tokens ise çıktı sınırına ulaşılmıştır. max_tokens değerini artırın veya modelden daha kısa yanıt isteyin.

Paylaşımlı hostingde Claude API kullanılabilir mi?

Evet; cURL açık ve dışarıya HTTPS bağlantısı mümkünse çalışır. Uzun yanıtlarda PHP’nin maksimum çalışma süresi ve hosting zaman aşımı sınırlarına dikkat edin.

Claude API yanıtlarını önbelleğe almalı mıyım?

Aynı girdiye aynı çıktının beklendiği durumlarda (ör. bir belgenin özeti) uygulama düzeyinde önbellek maliyeti ve gecikmeyi azaltır. Önbellek anahtarına model adını ve sistem talimatını da ekleyin; kişiye özel yanıtları paylaşılan önbellekte tutmayın.

İlk isteği göndermeden önce doğrulamalar

Örnek kodu çalıştırmadan önce ortam değişkenlerinin gerçekten yüklendiğini kontrol edin. getenv('ANTHROPIC_API_KEY') veya getenv('CLAUDE_MODEL') boş dönerse ağ isteği yapmayın; yapılandırma hatası üretin. Anahtarın kendisini günlük dosyasına yazmayın. Model kimliğini Anthropic’in güncel model listesi veya hesabınızın erişebildiği modeller üzerinden seçin. Böylece rehberde yazıldığı tarihte çalışan ama daha sonra kaldırılmış bir modeli kopyalayarak 404 ya da izin hatası yaşamazsınız.

İstek gövdesini oluştururken json_encode sonucunu kontrol edin. Geçersiz UTF-8 içeren kullanıcı metni veya desteklenmeyen bir değer kodlama hatası doğurabilir. Böyle bir durumda boş veya bozuk JSON’u API’ye göndermek yerine uygulama içinde açıklayıcı hata üretin. cURL bağlantısı kurulamazsa HTTP durum kodu sıfır olabilir; bunu API’nin 400 yanıtıyla karıştırmayın. Yanıt boşsa veya JSON’a ayrıştırılamıyorsa kullanıcıya ham hata metnini göstermek yerine kayıt numarasıyla güvenli bir hata mesajı verin.

Başarılı HTTP yanıtı her zaman tamamlanmış içerik midir?

HTTP 200 yalnızca isteğin API tarafından işlendiğini gösterir. Yanıtın content bloklarını türlerine göre okuyun; metin dışındaki bloklar araç çağrısı veya farklı çıktı olabilir. stop_reason değeri max_tokens ise metin sınırda kesilmiştir. Kesik JSON’u geçerli veri gibi kaydetmeyin. Araç kullanımı varsa modelin aracı çağırma isteği ve uygulamanın gerçekten gerçekleştirdiği işlem ayrı aşamalardır; silme, ödeme veya kullanıcıya mesaj gönderme gibi eylemler için ayrıca yetki ve insan onayı gerekir.

Token sayımı maliyet takibi için yararlı olsa da tek başına fatura tutarı değildir. Kullanılan model, girdi ve çıktı türleri, önbellek kullanımı ve ilgili fiyatlandırma koşulları değişebilir. Her istekte model kimliği, token kullanımı, istek kimliği, süre ve hata türünü kaydedin; ancak kullanıcıya ait gereksiz metni veya anahtarı günlüğe almayın. Bu kayıtlar 429 artışını, beklenmeyen maliyeti ve yavaş yanıtları ayırt etmeyi sağlar.

Tekrar deneme ve harcama kontrolü

400, 401 ve 403 gibi yapılandırma veya yetki hatalarını aynı gövdeyle tekrar göndermek sorunu çözmez. 429 yanıtında önce hesap sınırı ile geçici oran sınırını ayırın. Varsa retry-after değerine uyun; yoksa kısa, artan ve rastgeleleştirilmiş bekleme kullanın. Tekrar sayısına üst sınır koyun. Aynı kullanıcı isteği birden fazla kez gönderilirse uygulama kaydı, e-posta veya dosya yazımı iki kez oluşmamalıdır. API çağrısı saf metin üretimi olsa bile çağrıdan sonraki iş akışınız yan etki taşıyabilir.

Uzun yanıtlar için yalnızca toplam zaman aşımını yükseltmek çözüm değildir. Sunucu veya ara ağ bağlantıyı kapatabilir. Akışlı yanıtı seçiyorsanız parçalar geldiğinde hata çıkabileceğini, tamamlanmadan sonucu kalıcı kaydetmemeniz gerektiğini hesaba katın. Toplu ve gecikmeye duyarsız işler için kuyruk ve Message Batches yaklaşımını değerlendirin. Kullanıcı başına istek ve uzunluk sınırı, tek bir hesabın beklenmeyen harcama üretmesini engellemeye yardımcı olur.

Üretime almadan önce kısa test planı

Dört tür deneme yapın: kısa normal soru, çok uzun girdi, hatalı yapılandırma ve geçici API hatası. Normal soruda metin blokları birleşiyor mu? Uzun girdide uygulama limit koyuyor mu? Anahtar eksikse hata kullanıcıya güvenli biçimde aktarılıyor mu? 429 durumunda istek sonsuza kadar tekrarlanmıyor mu? Test ortamında gerçek anahtarı paylaşmadan bu akışları sahte HTTP yanıtlarıyla da sınayabilirsiniz. Son olarak model yanıtına kötü niyetli HTML eklendiğinde sayfada kod olarak çalışmadığını doğrulayın.

İstek kimliğiyle hata araştırma

Bir kullanıcı “yanıt gelmedi” dediğinde yalnızca ekrandaki genel hata mesajı yeterli değildir. İsteğe uygulama içinde bir takip kimliği verin ve ilgili API yanıtının request-id değerini, zamanını ve HTTP durumunu bu kimlikle ilişkilendirin. Sağlayıcının destek ekibine başvurmanız gerekirse bu kimlik sorunu bulmayı kolaylaştırır. Günlükte tüm kullanıcı sorusunu saklamak zorunda değilsiniz; görev türü, girdi uzunluğu ve güvenli bir iç referans çoğu teknik teşhis için yeterlidir. Böylece kişisel verilerin yanlışlıkla birden fazla günlük sistemine yayılmasını da sınırlandırırsınız.

Model yanıtını tarayıcıya döndürmeden önce beklenen türünü doğrulayın. Düz metin gösterecekseniz HTML kaçışı uygulayın. Markdown oluşturacaksanız güvenli bir ayrıştırıcı ve temizleme kuralları kullanın; yalnızca model “bu güvenlidir” dedi diye ürettiği bağlantı veya kodu çalıştırmayın. Dış web sayfasından alınan metinleri modele eklerseniz bu içerik uygulamanın sistem talimatı değildir. Bu sınır özellikle belge özetleme ve arama sonuçlarından cevap üretme uygulamalarında önemlidir.

Yapılandırılmış çıktı için uygulama doğrulaması

Bir ürün formundan marka, model ve fiyat çıkarmayı düşünün. Modelin JSON döndürmesi tek başına başarı sayılmaz. json_decode hatasını kontrol edin; alanların varlığını, sayıların aralığını, para birimini ve boş değerleri uygulama kurallarıyla doğrulayın. Eksik fiyatı sıfır kabul etmek gerçek bir siparişe yanlış fiyat yazabilir. Doğrulama başarısızsa veriyi kaydetmeyin; kullanıcıya eksik alanı gösterin veya yeniden değerlendirme isteyin. Sonuçları veritabanına yazan aşamayı üretim API çağrısından ayrı bir servis olarak tutmak test etmeyi kolaylaştırır.

Resmî başvuru: Claude Messages API, hata türleri ve model listesi.

İlgili Rehberler

Kaynaklar ve İleri Okuma

İlgili Yazılar

Yorum yapın