OpenAI API PHP entegrasyonu, bir PHP uygulamasından modele güvenli bir sunucu isteği gönderip yanıtı kullanıcıya kontrollü biçimde sunma işlemidir. Bu rehberde API anahtarını kaynak koda yazmadan saklayacak, Responses API’ye cURL ile istek gönderecek, yanıtı ayrıştıracak ve 401, 429 ile sunucu hatalarını yöneteceğiz.
Örnek, framework kullanmayan sade PHP ile hazırlanmıştır. Laravel kullanıyorsanız aynı sorumlulukları controller içine yığmak yerine ayrı bir servis sınıfına taşıyabilirsiniz. İlgili mimari için Laravel ile OpenAI API entegrasyonu rehberine bakabilirsiniz.
OpenAI API PHP entegrasyonu için gerekenler
Başlamadan önce PHP’de cURL uzantısının etkin olması, bir OpenAI Platform projesi ve bu projeye ait API anahtarı gerekir. Anahtar yalnızca sunucu tarafında kullanılmalıdır. Tarayıcıya gönderilen JavaScript’e, mobil uygulama paketine veya herkese açık Git deposuna eklenmemelidir.
- PHP 8.x ve etkin cURL uzantısı
- OpenAI Platform üzerinde oluşturulmuş proje anahtarı
- Ortam değişkenlerini okuyabilen sunucu yapılandırması
- İstek ve hata logları için güvenli, web dışı bir kayıt alanı
- Model kullanımını sınırlandıran bütçe ve rate limit planı
API anahtarını ortam değişkeninde saklayın
Yerel geliştirmede anahtarı terminal oturumuna veya Git tarafından izlenmeyen bir .env dosyasına ekleyebilirsiniz. Production ortamında hosting panelinin environment variable ya da secret yönetimini tercih edin:
export OPENAI_API_KEY="buraya-gercek-anahtarinizi-yazin"PHP tarafında anahtarı getenv('OPENAI_API_KEY') ile okuyun. Değer yoksa isteği başlatmadan kontrollü bir hata üretin. Anahtarın kendisini loglamayın ve hata çıktısında kullanıcıya göstermeyin.
Responses API’ye PHP cURL ile istek gönderme
OpenAI’nin güncel geliştirme akışı, metin üretimi ve araç kullanan uygulamalar için Responses API’yi kullanır. Aşağıdaki örnek, kullanıcıdan gelen metni doğrudan sistem komutu gibi çalıştırmaz; uzunluğu sınırlar ve yalnızca metin girdisi olarak API’ye yollar.
<?php
function askOpenAI(string $userInput): string
{
$apiKey = getenv('OPENAI_API_KEY');
if (!$apiKey) {
throw new RuntimeException('OPENAI_API_KEY tanımlı değil.');
}
$userInput = trim($userInput);
if ($userInput === '' || mb_strlen($userInput) > 4000) {
throw new InvalidArgumentException('İstek metni 1-4000 karakter olmalıdır.');
}
$payload = [
'model' => 'gpt-5.6-terra',
'input' => [
[
'role' => 'developer',
'content' => 'Kısa, doğru ve Türkçe yanıt ver. Bilmediğin bilgiyi uydurma.',
],
[
'role' => 'user',
'content' => $userInput,
],
],
'max_output_tokens' => 600,
];
$ch = curl_init('https://api.openai.com/v1/responses');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(
$payload,
JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
if ($body === false) {
throw new RuntimeException('Ağ hatası: ' . $curlError);
}
$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status < 200 || $status >= 300) {
$message = $data['error']['message'] ?? 'OpenAI API isteği başarısız.';
throw new RuntimeException("API hatası ({$status}): {$message}");
}
foreach ($data['output'] ?? [] as $item) {
if (($item['type'] ?? '') !== 'message') {
continue;
}
foreach ($item['content'] ?? [] as $content) {
if (($content['type'] ?? '') === 'output_text') {
return trim($content['text'] ?? '');
}
}
}
throw new RuntimeException('Yanıtta metin çıktısı bulunamadı.');
}Örnekte model olarak maliyet ve yetenek dengesi için gpt-5.6-terra kullanılmıştır. Model kataloğu zaman içinde değişebileceği için production’a almadan önce hesabınızda erişilebilen modeli resmî model sayfasından doğrulayın. Model adını kullanıcıdan gelen istekle değiştirmeyin; sunucu tarafında izin verilen modeller listesi tutun.
Form isteğini güvenli biçimde işleme
Fonksiyonu bir form veya API endpoint’i üzerinden çağırıyorsanız kimlik doğrulama, CSRF koruması, istek boyutu sınırı ve kullanıcı bazlı rate limit ekleyin. Model çıktısını HTML olarak doğrudan basmayın. Düz metin gösterecekseniz htmlspecialchars() ile escape edin:
<?php
try {
$question = $_POST['question'] ?? '';
$answer = askOpenAI($question);
echo nl2br(
htmlspecialchars($answer, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')
);
} catch (Throwable $e) {
error_log($e->getMessage());
http_response_code(500);
echo 'İstek şu anda tamamlanamadı.';
}Bu yaklaşım ayrıntılı teknik hatayı sunucu loguna yazar, ziyaretçiye ise API anahtarı veya sağlayıcı ayrıntısı içermeyen genel bir mesaj gösterir. Public bir uygulamada kullanıcı girdisinin kötüye kullanımını azaltmak için oturum, IP veya hesap bazlı kota uygulayın.
OpenAI API hataları nasıl yönetilir?
401: Geçersiz veya eksik API anahtarı
Ortam değişkeninin web sunucusu sürecine ulaştığını kontrol edin. Anahtarı ekrana yazdırmak yerine yalnızca değişkenin boş olup olmadığını doğrulayın. Anahtarın sızdığından şüpheleniyorsanız eski anahtarı iptal edip yenisini oluşturun.
400: İstek gövdesi veya parametre hatası
JSON yapısını, model adını ve gönderdiğiniz alanları kontrol edin. API’nin döndürdüğü hata mesajını geliştirici logunda saklayın; kullanıcıya ham yanıtı göstermeyin. Güncel parametreler için Responses API dokümantasyonunu esas alın.
429: Rate limit veya kullanım kotası
Her 429 yanıtını sınırsızca tekrar göndermek sorunu büyütür. Yeniden denemelerde artan bekleme süresi ve rastgele küçük gecikme kullanın; maksimum deneme sayısı belirleyin. Kullanıcı bazlı kota, kısa süreli cache ve daha küçük çıktı sınırı gereksiz istekleri azaltır.
5xx: Geçici servis veya ağ hatası
Bağlantı ve okuma zaman aşımı tanımlayın. Yalnızca tekrar denenebilir hatalarda sınırlı sayıda retry uygulayın. Kritik işlemlerde isteği bir queue’ya almak, ziyaretçinin HTTP bağlantısını uzun süre açık tutmaktan daha dayanıklıdır. Daha ayrıntılı teşhis için OpenAI API hataları ve çözüm yolları yazısını kullanabilirsiniz.
Maliyet, gizlilik ve performans kontrolleri
- Girdi sınırı: Kullanıcının gereksiz uzun metin göndermesini engelleyin.
- Çıktı sınırı:
max_output_tokensdeğerini kullanım senaryosuna göre belirleyin. - Model seçimi: En güçlü modeli varsayılan kabul etmeyin; kalite, gecikme ve maliyeti gerçek örneklerle ölçün.
- Kişisel veri: Gerekmeyen kimlik, iletişim veya müşteri bilgisini modele göndermeyin.
- Loglar: API anahtarı ve ham kişisel verileri loglamayın; istek kimliği, durum kodu ve süre gibi teknik alanları kaydedin.
- Cache: Aynı ve kişisel olmayan sorular için kısa süreli cache değerlendirin.
Responses API’nin yapısı ve eski uç noktalardan farkları için OpenAI Responses API rehberi, diğer yapay zekâ entegrasyonları için AI API kategorisi kullanılabilir.
Sık sorulan sorular
OpenAI’nin resmî PHP SDK’sı var mı?
OpenAI quickstart sayfasında resmî SDK’lar JavaScript, Python, .NET, Java, Go ve Ruby için listelenir. PHP’de doğrudan HTTPS/cURL kullanabilir veya seçtiğiniz topluluk paketinin bakım ve güvenlik durumunu ayrıca değerlendirebilirsiniz.
API anahtarı JavaScript içinde kullanılabilir mi?
Hayır. Tarayıcıya gönderilen anahtar ziyaretçi tarafından görülebilir ve kötüye kullanılabilir. İstek, kimlik doğrulama ve kota uygulayabileceğiniz kendi PHP sunucunuz üzerinden yapılmalıdır.
Hangi model seçilmeli?
Seçim; istenen kalite, gecikme, araç kullanımı ve bütçeye bağlıdır. Önce temsilî test soruları oluşturun, erişebildiğiniz güncel modelleri aynı başarı ölçütleriyle karşılaştırın ve model kimliğini sunucu yapılandırmasında yönetin.
Yanıt boş gelirse ne kontrol edilmeli?
HTTP durumunu, ham JSON’un output dizisini ve içerik türlerini log üzerinde inceleyin. Sadece ilk dizi elemanına güvenmek yerine örnekteki gibi message ve output_text öğelerini arayın.
İstekler tekrar denenmeli mi?
Geçici ağ, rate limit ve 5xx hataları sınırlı sayıda ve artan beklemeyle yeniden denenebilir. Geçersiz anahtar veya hatalı istek gövdesi gibi kalıcı hataları düzeltmeden tekrar göndermek fayda sağlamaz.
Sonuç
Güvenli bir OpenAI API PHP entegrasyonu; anahtarı ortam değişkeninde saklar, Responses API’ye sunucu tarafından istek gönderir, girdiyi ve çıktıyı sınırlar, hata türlerini ayırır ve kullanıcıya ham hata göstermeden loglama yapar. Örneği önce geliştirme veya staging ortamında deneyin; gerçek kullanıcı trafiğine açmadan önce kota, gizlilik ve kötüye kullanım kontrollerini tamamlayın.
Resmî kaynaklar
