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

Son güncelleme

Gemini API ile PHP entegrasyonunda uygulamanız sunucu tarafında Google’ın üretken yapay zekâ API’sine HTTP isteği gönderir, dönen yanıtı ayrıştırır ve sonucu kullanıcıya veya veritabanına aktarır. PHP için Google’ın diğer diller kadar yaygın kullanılan resmi bir SDK’sı bulunmadığından, en anlaşılır ve bağımlılığı en az yöntem doğrudan REST uç noktasını cURL veya Guzzle ile çağırmaktır. Model ve uç nokta adları zamanla değişebildiği için internetten kopyalanmış eski örnekleri çalıştırmadan önce mutlaka resmi belgeyi kontrol edin. Bu rehberde API anahtarının güvenli saklanmasından ilk isteğin gönderilmesine, yanıtın doğru ayrıştırılmasından hata yönetimine, JSON çıktı almaktan maliyet kontrolüne kadar canlı bir projede ihtiyaç duyacağınız adımları ele alıyoruz.

Başlamadan önce: anahtar ve model seçimi

Gemini API anahtarı ve model seçimi

Gemini API’yi kullanmak için Google AI Studio üzerinden bir API anahtarı oluşturmanız gerekir. Bu 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ı koda yazmayın: Anahtarı .env dosyasında veya sunucu ortam değişkeninde tutun. .env dosyasının Git deposuna eklenmediğinden ve web kök dizininden erişilemediğinden emin olun.
  • Tarayıcıya göndermeyin: Anahtar yalnızca sunucuda kullanılmalı; JavaScript kodunda, HTML’de veya API yanıtlarında yer almamalıdır.
  • Kısıtlama ekleyin: Google Cloud konsolunda anahtarı yalnızca gerekli API ile sınırlamak, olası bir sızıntının etkisini azaltır.
  • Model adını yapılandırmada tutun: Model adlarını koda gömmek yerine bir ayar değişkeninde saklayın. Google yeni model sürümleri çıkardıkça veya eski sürümleri emekliye ayırdıkça tek bir satırla geçiş yapabilirsiniz.

Hangi modellerin hesabınızda kullanılabilir olduğunu görmek için API’nin model listeleme uç noktasını çağırabilirsiniz. Bu, “model bulunamadı” hatalarının en hızlı teşhis yöntemidir; ayrıntılar için Gemini API Model Not Found rehberimize bakabilirsiniz.

İstek yapısı nasıl çalışır?

Metin üretimi için generateContent yöntemine, URL’de model adını belirterek POST isteği gönderilir. İstek gövdesinin temel alanı contents dizisidir; her öğe bir rol (user veya model) ve bir parts listesi içerir. Çok turlu bir sohbette önceki mesajlar bu diziye sırayla eklenir.

İsteğe eklenebilecek diğer önemli alanlar şunlardır:

  • systemInstruction: Modelin rolünü, üslubunu ve kurallarını belirleyen sistem talimatı. Kullanıcı mesajından ayrı tutulması, talimatların daha tutarlı uygulanmasını sağlar.
  • generationConfig: Üretim ayarları. maxOutputTokens ile çıktı uzunluğunu sınırlayabilir, temperature ile yaratıcılık düzeyini ayarlayabilirsiniz.
  • safetySettings: Zararlı içerik kategorileri için engelleme eşiklerini belirler.

cURL ile ilk istek

Aşağıdaki örnek, ek kütüphane gerektirmeden PHP’nin cURL eklentisiyle bir metin üretim isteği gönderir. Uç nokta biçimini ve sürüm ön ekini (ör. v1beta) kullandığınız tarihteki resmi belgeyle karşılaştırın.

<?php
function geminiUret(string $soru): array
{
    $model = getenv('GEMINI_MODEL');                  // ör. yapılandırmadaki güncel model adı
    $url   = "https://generativelanguage.googleapis.com/v1beta/models/{$model}:generateContent";

    $govde = [
        'systemInstruction' => ['parts' => [['text' => 'Kısa ve Türkçe cevap ver.']]],
        'contents' => [
            ['role' => 'user', 'parts' => [['text' => $soru]]],
        ],
        'generationConfig' => ['maxOutputTokens' => 800, 'temperature' => 0.4],
    ];

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-goog-api-key: ' . getenv('GEMINI_API_KEY'),
        ],
        CURLOPT_POSTFIELDS     => json_encode($govde, JSON_UNESCAPED_UNICODE),
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT        => 60,
    ]);
    $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)];
}

Anahtarı URL’ye sorgu parametresi olarak eklemek yerine x-goog-api-key başlığıyla göndermek, anahtarın sunucu erişim kayıtlarına ve hata mesajlarına düşme riskini azaltır. JSON_UNESCAPED_UNICODE bayrağı Türkçe karakterlerin kaçış dizilerine dönüşmesini engeller; bu zorunlu değildir ama hata ayıklamayı kolaylaştırır.

Laravel kullanıyorsanız aynı isteği Http::withHeaders([...])->timeout(60)->post($url, $govde) ile daha kısa yazabilir, retry() metoduyla geçici hatalarda otomatik tekrar deneme ekleyebilirsiniz.

Kodu bir servis sınıfında toplamak

API çağrısı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ı ve tekrar deneme kurallarını tek yerden yönetir; uygulamanın geri kalanı ise yalnızca “bu soruya cevap üret” der. İleride Gemini yerine başka bir sağlayıcıya geçmek veya iki sağlayıcıyı birlikte kullanmak istediğinizde değiştirmeniz gereken tek yer bu sınıf olur.

final class GeminiServisi
{
    public function __construct(
        private string $anahtar,
        private string $model,
        private int $zamanAsimi = 60,
    ) {}

    public function cevapla(string $soru, ?string $sistem = null): GeminiYaniti
    {
        // 1) isteği oluştur  2) gönder  3) hata kodunu ele al
        // 4) finishReason ve promptFeedback'i kontrol et
        // 5) metni ve kullanım bilgisini GeminiYaniti nesnesine dönüştür
    }
}

Dönen değeri basit bir dizi yerine küçük bir nesneyle (GeminiYaniti) temsil etmek, “metin var mı, kesildi mi, kaç token harcandı” gibi soruları açık metotlarla sormanızı sağlar. Testlerde ise servis sınıfının yerine sahte bir sınıf koyarak gerçek API’ye istek göndermeden uygulamanızı test edebilirsiniz.

Yanıtı doğru ayrıştırmak

Gemini API yanıtını ve hata durumunu doğrulama

Başarılı bir yanıtta üretilen metin genellikle candidates[0].content.parts[0].text yolunda bulunur. Ancak bu yolu körü körüne okumak, canlı ortamda en sık karşılaşılan hatalardan birine yol açar: yanıt her zaman bir metin içermez.

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

if ($sonuc['durum'] !== 200) {
    $mesaj = $veri['error']['message'] ?? 'Bilinmeyen hata';
    // durum koduna göre ele al (aşağıdaki bölüme bakın)
}

if (! empty($veri['promptFeedback']['blockReason'])) {
    // istem, güvenlik nedeniyle hiç işlenmedi
}

$aday   = $veri['candidates'][0] ?? null;
$neden  = $aday['finishReason'] ?? null;      // STOP, MAX_TOKENS, SAFETY ...
$metin  = '';
foreach ($aday['content']['parts'] ?? [] as $parca) {
    $metin .= $parca['text'] ?? '';
}

$kullanim = $veri['usageMetadata'] ?? [];      // token sayıları

Dikkat edilmesi gereken durumlar:

  • Boş aday listesi: İstem güvenlik filtresine takılmışsa candidates boş gelebilir ve sebep promptFeedback alanında yer alır.
  • finishReason değeri: STOP normal tamamlanmayı, MAX_TOKENS çıktının sınıra ulaşıp kesildiğini, SAFETY ise yanıtın güvenlik nedeniyle durdurulduğunu gösterir. Kesilmiş bir yanıtı tamamlanmış gibi kullanıcıya göstermeyin.
  • Birden fazla parça: Yanıt birden fazla parts öğesi içerebilir; yalnızca ilkini okumak metnin bir kısmını kaybetmenize neden olabilir.
  • Kullanım bilgisi: usageMetadata içindeki girdi ve çıktı token sayılarını kaydetmek, maliyet takibinin temelidir.

Hata yönetimi

HTTP hatası, boş aday, güvenlik nedeniyle durdurulmuş yanıt ve beklenmeyen içerik biçimini ayrı ele alın. API, hata durumunda bir error nesnesi içinde kod, mesaj ve durum adı döndürür.

  • 400 (INVALID_ARGUMENT): İstek gövdesi hatalı. Alan adlarını, JSON yapısını ve parametre değerlerini kontrol edin. Tekrar denemek işe yaramaz.
  • 403 (PERMISSION_DENIED): Anahtar geçersiz, kısıtlanmış veya ilgili API için yetkisiz.
  • 404 (NOT_FOUND): Model adı yanlış veya model artık kullanılmıyor.
  • 429 (RESOURCE_EXHAUSTED): Oran veya kota sınırı aşıldı. Artan bekleme süreleriyle (exponential backoff) tekrar deneyin ve kullanıcıya anlaşılır bir mesaj gösterin.
  • 500 ve 503: Sağlayıcı tarafında geçici sorun. Sınırlı sayıda tekrar deneme uygundur.

Tekrar denemede aynı kullanıcı işlemini iki kez kaydetmeyin. Örneğin üretilen metni veritabanına yazan bir işlemde, yazma adımını yalnızca başarılı ve tamamlanmış yanıttan sonra, tek seferlik bir işlem kimliğiyle yapın. Zaman aşımı, oran sınırı ve sağlayıcı kesintisine karşı kullanıcıya “şu anda yanıt üretilemiyor, lütfen birkaç dakika sonra tekrar deneyin” gibi açık bir durum gösterin.

JSON çıktı almak

Model çıktısını bir veritabanı kaydına veya arayüz bileşenine dönüştürecekseniz serbest metin yerine yapılandırılmış JSON istemek işinizi kolaylaştırır. Gemini API, generationConfig içinde yanıt türünü application/json olarak belirtmenize ve bir yanıt şeması tanımlamanıza izin verir.

'generationConfig' => [
    'responseMimeType' => 'application/json',
    'responseSchema'   => [
        'type'       => 'OBJECT',
        'properties' => [
            'baslik'   => ['type' => 'STRING'],
            'ozet'     => ['type' => 'STRING'],
            'etiketler'=> ['type' => 'ARRAY', 'items' => ['type' => 'STRING']],
        ],
        'required'   => ['baslik', 'ozet'],
    ],
],

Şema, çıktının biçimini düzenler ama içeriğin doğru olduğunu garanti etmez. Dönen JSON’u json_decode ile ayrıştırdıktan sonra zorunlu alanları, uzunlukları ve izin verilen değerleri kendi kurallarınızla yeniden doğrulayın.

Çok turlu sohbet ve bağlam yönetimi

Gemini API durumsuzdur; yani önceki mesajları hatırlamaz. Bir sohbet uygulamasında modelin önceki konuşmayı bilmesini istiyorsanız her istekte geçmiş mesajları contents dizisine sırayla eklemeniz gerekir. Kullanıcı mesajları user, modelin önceki yanıtları ise model rolüyle gönderilir.

$contents = [];
foreach ($gecmis as $mesaj) {                  // veritabanından sıralı olarak okunur
    $contents[] = [
        'role'  => $mesaj['kimden'] === 'kullanici' ? 'user' : 'model',
        'parts' => [['text' => $mesaj['metin']]],
    ];
}
$contents[] = ['role' => 'user', 'parts' => [['text' => $yeniSoru]]];

Bu yaklaşımın doğal sonucu, sohbet uzadıkça her isteğin daha fazla girdi token’ı içermesi ve maliyetin artmasıdır. Uzun sohbetlerde şu yöntemler işe yarar:

  • Kayan pencere: Yalnızca son belirli sayıda mesajı gönderin.
  • Özetleme: Eski mesajları belirli aralıklarla kısa bir özete dönüştürüp bu özeti sistem talimatına veya ilk mesaja ekleyin.
  • Konu ayırma: Kullanıcı yeni bir konuya geçtiğinde yeni bir sohbet başlatmasını önerin.

Sohbet geçmişini saklarken her mesajın hangi kullanıcıya ait olduğunu sunucuda doğrulayın. Geçmişi istemciden gelen bir diziye güvenerek oluşturmak, kullanıcının sahte “model” mesajları ekleyerek modeli yönlendirmesine kapı açar.

Görsel ve dosya girdileri

Gemini modelleri çok modludur; metnin yanında görsel, PDF ve ses gibi girdileri de işleyebilir. Küçük dosyalar parts içinde inline_data alanıyla base64 kodlanmış olarak gönderilebilir; büyük dosyalar için ise önce Files API ile yükleyip dönen dosya referansını kullanmak önerilir. Kullanıcıların yüklediği dosyaları API’ye göndermeden önce tür ve boyut kontrolü yapın, gizli belgelerin gönderilmesi konusunda kullanıcıyı bilgilendirin. Dosya yükleme güvenliği için Laravel dosya yükleme rehberimizdeki ilkeler PHP projelerinin geneline uygulanabilir.

Güvenlik ve kullanıcı verisi

Kullanıcı girdisi uzun veya hassassa istek boyutu, kullanıcı izni ve veri saklama politikasını önceden belirleyin. Kişisel verileri, müşteri bilgilerini veya gizli iş verilerini API’ye göndermeden önce sağlayıcının veri kullanım koşullarını inceleyin ve gerekirse maskeleyin.

  • Çıktıyı kaçışla gösterin: Model yanıtını ekrana basarken htmlspecialchars() ile HTML kaçışı uygulayın. Markdown’ı HTML’e çeviriyorsanız güvenli bir dönüştürücü ve temizleyici kullanın.
  • Girdi sınırı koyun: Kullanıcı başına mesaj uzunluğu ve günlük istek sayısı sınırı, hem maliyeti hem de kötüye kullanımı kontrol altında tutar.
  • Prompt injection’a dikkat: Kullanıcının veya dış bir kaynağın metni, sistem talimatınızı geçersiz kılmaya çalışabilir. Model yanıtına dayanarak kritik işlemleri otomatik yapmayın.

Maliyet ve performans

Gemini API’de ücretlendirme, kullanılan modele ve girdi ile çıktı token sayısına göre yapılır; fiyatlar ve ücretsiz kullanım sınırları zaman içinde değiştiği için güncel fiyat sayfasını kontrol edin. Maliyeti kontrol altında tutmak için:

  • Görevin gerektirdiği en hafif modeli seçin; basit sınıflandırma veya özetleme için en büyük modele ihtiyaç olmayabilir.
  • maxOutputTokens ile çıktı uzunluğunu sınırlayın.
  • Aynı sorulara verilen cevapları önbelleğe alın.
  • Uzun sohbet geçmişini her istekte tamamen göndermek yerine özetleyin.
  • Toplu işleri kullanıcı isteğinden ayırıp kuyrukta çalıştırın.

Kullanıcının uzun yanıtı beklerken boş ekranla karşılaşmaması için akış (streaming) yöntemini kullanabilirsiniz; ayrıntılar Streaming API rehberimizde.

Canlı sistem kontrol listesi

  • API anahtarı ortam değişkeninde, depoda ve tarayıcıda yok.
  • Model adı yapılandırmadan okunuyor; model listesi ile doğrulandı.
  • Bağlantı ve toplam zaman aşımı tanımlı.
  • 429 ve 5xx için sınırlı, artan beklemeli tekrar deneme var.
  • finishReason ve promptFeedback kontrol ediliyor; kesik yanıtlar ayrı ele alınıyor.
  • Token kullanımı istek bazında kaydediliyor.
  • Çıktı ekrana kaçışla basılıyor; JSON çıktılar ayrıca doğrulanıyor.
  • Fiyat, mevzuat ve sağlık gibi konularda model yanıtı bağımsız kaynakla denetleniyor.

API yolunu belgeyle eşleştirin

Gemini geliştirici belgelerinde generateContent REST yöntemi bulunur; yeni başlangıç sayfasında Interactions API de anlatılır. Bu rehberin cURL ve PHP kodu generateContent yolunu kullanır. İki API biçiminin istek ve yanıt yapısı aynı kabul edilmemelidir. Bir belge örneğini kopyalarken uç nokta, model adı ve kullanılan API biçiminin birbiriyle uyumlu olduğundan emin olun. Model listesi değişebildiği için örnekteki sabit adı üretim uygulamasının tek kaynağı yapmayın.

İlk denemeyi gizli veri içermeyen kısa bir metinle yapın. Anahtarı x-goog-api-key başlığında gönderin; URL sorgu dizgesine yazmayın. HTTP 200 yanıtı tek başına kullanılabilir metin garanti etmez: aday listesi, durdurma nedeni ve içerik parçaları kontrol edilmelidir. Yanıt alanlarını doğrudan dizi konumuyla okuyorsanız boş aday durumunda PHP uyarısı alabilirsiniz. Eksik alanları ayrı hata olarak ele alın ve kullanıcıya güvenli açıklama gösterin.

Yanıt doğrulamasını iş kuralına bağlayın

Modelden JSON istediğinizde dahi uygulama tarafında JSON çözümleme ve alan doğrulaması yapın. Beklenen anahtarların bulunması, türlerinin doğru olması ve uzunluk sınırlarına uyması gerekir. Bir e-ticaret etiketleme işinde modelin döndürdüğü kategori, veritabanında izin verilen kategori listesiyle eşleşmelidir. Serbest metni SQL, HTML veya kabuk komutu olarak doğrudan çalıştırmayın. Model çıktısı güvenilmeyen uygulama verisidir; kullanıcının girdiği metinle aynı dikkatle işlenmelidir.

Dosya veya görsel gönderecekseniz izin, veri sınıflandırması, dosya boyutu ve saklama koşullarını daha önce belirleyin. Kullanıcıya ait özel dosyayı yalnız teknik olarak yüklenebildiği için harici API’ye göndermeyin. API maliyeti de eklenen bağlamla büyür; uzun sohbet geçmişini her istekte tam göndermek yerine amaca uygun sınır koyun. Kullanıcının gördüğü sonuçta kaynağı ve belirsizliği gizlemeyin.

Üretimde hata ve maliyet izlemesi

401 veya 403 yanıtında anahtar ve izin yapılandırmasını inceleyin; aynı isteği durmadan tekrarlamak fayda sağlamaz. 404 model adı veya yöntem uyumsuzluğunu gösterebilir. 429 oran sınırı ya da kullanım sınırı olabilir; yanıt ayrıntısını okuyun. Geçici hatalar için sınırlı ve gecikmeli tekrar deneyin. Zaman aşımında uygulama işinin gerçekten tamamlanıp tamamlanmadığını düşünerek çift ücretli çağrıyı önleyin. Kayıtlarda anahtar ve kullanıcıya ait ham özel içerik olmasın; model, süre, sonuç ve güvenli istek kimliği yeterlidir.

Model ve fiyatı ürün değişkeni olarak yönetin. Ücretsiz kullanım veya maliyet değerlerini makaleden ezbere almayın; hesabınızın ve modelin güncel sayfasına bakın. Küçük deneme kümesiyle doğruluk, gecikme ve maliyeti birlikte ölçün. Bir modeli değiştirdiğinizde yalnız başarılı ilk isteği değil, boş yanıt ve yapılandırılmış çıktı testlerini de yeniden çalıştırın. Kaynaklar: Gemini API başvurusu ve başlangıç belgesi.

Bir isteğin güvenli yaşam döngüsü

Uygulama kullanıcıdan gelen metni önce doğrular: uzunluk, izin ve beklenen görev türü kontrol edilir. Sunucu, erişimi olan API anahtarını yalnız kendi ortamından okur ve model adını yapılandırmadan seçer. İstek tamamlandığında HTTP durumu, yanıt biçimi, aday içeriği ve durdurma nedeni birlikte değerlendirilir. Ardından içerik uygulamanın izin verdiği alana dönüştürülür. Bu zincirin her adımı ayrı hata verebilir; tüm başarısızlıkları “Gemini çalışmıyor” diye tek mesaja indirgemek teşhisi zorlaştırır.

Örneğin kullanıcı bir ürün açıklaması oluşturuyorsa modelden ürünün teknik özelliklerini uydurmaması istenir. Buna rağmen dönen metindeki kapasite, fiyat veya garanti bilgisi ürün veritabanıyla karşılaştırılmalıdır. Modelin cevabını hemen yayımlamak yerine editöre taslak olarak gösterin. Bu yaklaşım hem yanlış bilginin hem kullanıcı girdisiyle tetiklenen istenmeyen çıktının etkisini sınırlar. API çağrısı başarılı olsa bile yayına alma ayrı bir iş kararıdır.

Testlerde boş candidates dizisi, beklenmeyen parts biçimi, geçersiz JSON, zaman aşımı ve iptal edilmiş istek bulunmalıdır. Ayrıca anahtarın değişmesi, modelin erişimden kalkması ve kota dolması gibi gerçek işletim olaylarına karşı anlaşılır uyarı hazırlayın. Uygulama yeniden deneyecekse aynı işlemin iki kez veri tabanına yazılmadığını doğrulayın. Kullanıcıya geri dönen hata ayrıntısı API anahtarı, iç sunucu yolu veya özel veri içermemelidir.

Sıkça Sorulan Sorular

Gemini API için resmi bir PHP SDK’sı var mı?

Google, Gen AI SDK’larını Python, JavaScript, Go ve Java gibi diller için sunar. PHP tarafında topluluk tarafından geliştirilen paketler bulunsa da REST uç noktasını doğrudan çağırmak hem bağımlılığı azaltır hem de API değişikliklerini takip etmeyi kolaylaştırır.

“Model not found” hatası alıyorum, ne yapmalıyım?

Kullandığınız model adının hâlâ desteklendiğini ve API sürüm ön ekinin doğru olduğunu kontrol edin. Model listeleme uç noktasını çağırarak hesabınızda kullanılabilir modelleri görebilirsiniz.

Yanıt neden yarıda kesiliyor?

finishReason değeri MAX_TOKENS ise çıktı sınırına ulaşılmıştır; maxOutputTokens değerini artırın veya daha kısa yanıt isteyin. SAFETY ise yanıt güvenlik filtresine takılmıştır.

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

Evet; sunucunuzda cURL eklentisi açıksa ve dışarıya HTTPS bağlantısı yapılabiliyorsa çalışır. Ancak uzun süren isteklerde PHP’nin maksimum çalışma süresi ve hosting firmasının zaman aşımı sınırlarına dikkat edin.

Gemini API yanıtlarını önbelleğe almak doğru mu?

Aynı girdiye aynı çıktının beklendiği durumlarda (ör. bir ürün açıklamasının özeti veya sabit bir metnin çevirisi) önbellek hem maliyeti hem gecikmeyi azaltır. Önbellek anahtarını model adı, sistem talimatı ve kullanıcı girdisinin birleşiminden oluşturun; böylece modeli veya talimatı değiştirdiğinizde eski yanıtlar otomatik olarak geçersiz kalır. Kişiye özel ve hassas yanıtları paylaşılan bir önbellekte tutmayın.

İlgili Rehberler

Kaynaklar ve İleri Okuma

İlgili Yazılar

Yorum yapın