PHP ile ChatGPT API Entegrasyonu: Adım Adım AI Chatbot Geliştirme (2026)

Yapay zekâ teknolojilerini PHP projelerinize entegre etmek için yeni bir programlama dili öğrenmeniz veya kendi yapay zekâ modelinizi geliştirmeniz gerekmiyor. OpenAI API sayesinde mevcut PHP uygulamalarınıza metin üretimi, akıllı sohbet, içerik analizi ve otomatik yanıt oluşturma gibi özellikler ekleyebilirsiniz.

Bu rehberde PHP ile ChatGPT API entegrasyonunu sıfırdan ele alacağız. API anahtarı oluşturmadan ilk HTTP isteğine, güvenli yapılandırmadan sohbet geçmişi yönetimine kadar tüm süreci uygulamalı örneklerle inceleyeceğiz.

Örnekler PHP 8.1 ve üzeri, cURL ve OpenAI Responses API temel alınarak hazırlanmıştır.

1. OpenAI API Nedir? PHP Projelerinde Nasıl Kullanılır?

OpenAI API, yazılım uygulamalarının OpenAI tarafından sunulan yapay zekâ modelleriyle iletişim kurmasını sağlayan bir programlama arayüzüdür. PHP uygulamanız üzerinden modele metin gönderebilir, oluşturulan yanıtları alabilir ve bu yanıtları kendi yazılım süreçlerinizde kullanabilirsiniz.

OpenAI API ile PHP projelerinde geliştirebileceğiniz uygulamalardan bazıları şunlardır:

• Yapay zekâ destekli chatbot sistemleri.

• E-ticaret ürün açıklaması oluşturucuları.

• Otomatik blog ve içerik üretim araçları.

• Müşteri destek ve soru-cevap sistemleri.

• Metin analizi ve sınıflandırma uygulamaları.

• Otomatik e-posta ve içerik oluşturma sistemleri.

PHP ve OpenAI API arasındaki iletişim nasıl çalışır?

1. Kullanıcı web arayüzünden bir mesaj gönderir.

2. PHP backend gelen mesajı karşılar.

3. PHP sunucusu OpenAI API adresine HTTP isteği gönderir.

4. Yapay zekâ modeli isteği işleyerek yanıt oluşturur.

5. PHP yanıtı işler ve kullanıcıya iletir.

Bu mimaride API anahtarı sunucu tarafında tutulur. Böylece gizli bilgiler tarayıcıya gönderilmeden güvenli bir entegrasyon oluşturulabilir.

2. OpenAI API Key Nasıl Alınır?

PHP uygulamanızın OpenAI API ile iletişim kurabilmesi için bir API anahtarına ihtiyacınız vardır. API anahtarı, uygulamanızın OpenAI platformunda kimlik doğrulaması yapmasını sağlar.

API anahtarı oluşturma adımları

1. OpenAI Platform adresini açın.

2. OpenAI hesabınızla giriş yapın.

3. API Keys bölümüne gidin.

4. Yeni bir secret API key oluşturun.

5. Oluşturulan anahtarı güvenli bir yerde saklayın.

6. API projenizin faturalandırma ve kullanım limitlerini kontrol edin.

ChatGPT aboneliği API kullanımını kapsıyor mu?

Hayır. ChatGPT Plus veya Pro aboneliği, PHP uygulamanızdan gönderdiğiniz API isteklerini otomatik olarak karşılamaz. ChatGPT aboneliği ile OpenAI API platformunun faturalandırması birbirinden ayrıdır.

API kullanımı seçilen modele, girdi tokenlarına ve çıktı tokenlarına göre ücretlendirilir. Güncel fiyatlandırmayı OpenAI API Pricing sayfasından inceleyebilirsiniz.

3. PHP ile OpenAI API'ye İlk İstek Nasıl Gönderilir?

OpenAI API ile iletişim kurmak için PHP tarafında HTTP isteği göndermemiz gerekir. Bunun için PHP'nin yerleşik cURL eklentisini kullanabiliriz. Bu yöntem herhangi bir harici PHP kütüphanesi gerektirmez.

Gerekli PHP eklentileri

Öncelikle sunucunuzda cURL eklentisinin etkin olduğundan emin olun. Terminal üzerinden aşağıdaki komutu çalıştırabilirsiniz:

Terminal komutu:

php -m | grep curl

Komut çıktısında curl görünüyorsa gerekli PHP eklentisi etkin demektir.

OpenAI Responses API adresi

Bu örnekte OpenAI Responses API kullanılacaktır. İstek gönderilecek endpoint adresi şöyledir:

POST https://api.openai.com/v1/responses

PHP cURL ile ilk API isteği

Aşağıdaki PHP örneği, OpenAI API'ye bir metin gönderir ve modelin oluşturduğu yanıtı ekrana yazdırır.

PHP uygulama kodu:

declare(strict_types=1);

$apiKey = getenv('OPENAI_API_KEY');

$model = getenv('OPENAI_MODEL');

if (!$apiKey || !$model) {

throw new RuntimeException('API yapılandırması eksik.');

}

$payload = [

'model' => $model,

'instructions' => 'Türkçe yanıt veren yardımcı bir PHP asistanısın.',

'input' => 'PHP ile PDO kullanarak MySQL bağlantısı nasıl kurulur?',

'max_output_tokens' => 500,

];

$ch = curl_init('https://api.openai.com/v1/responses');

curl_setopt_array($ch, [

CURLOPT_POST => true,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_HTTPHEADER => [

'Content-Type: application/json',

'Authorization: Bearer ' . $apiKey,

],

CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),

CURLOPT_CONNECTTIMEOUT => 10,

CURLOPT_TIMEOUT => 60,

]);

$response = curl_exec($ch);

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

$error = curl_error($ch);

curl_close($ch);

if ($response === false) {

throw new RuntimeException('Bağlantı hatası: ' . $error);

}

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);

if ($httpCode < 200 || $httpCode >= 300) {

$message = $data['error']['message'] ?? 'API isteği başarısız.';

throw new RuntimeException($message, $httpCode);

}

foreach ($data['output'] ?? [] as $item) {

if (($item['type'] ?? '') !== 'message') {

continue;

}

foreach ($item['content'] ?? [] as $content) {

if (($content['type'] ?? '') === 'output_text') {

echo htmlspecialchars($content['text'], ENT_QUOTES, 'UTF-8');

}

}

}

Bu örnekte model adı ortam değişkeninden alınmaktadır. Kullanabileceğiniz güncel model kimliklerini OpenAI Model Kataloğu üzerinden kontrol edebilirsiniz.

4. API Anahtarını .env Dosyasında Güvenli Saklamak

API anahtarını doğrudan PHP dosyasına yazmak ciddi bir güvenlik riskidir. Kaynak kodun GitHub'a yüklenmesi, paylaşılması veya yedeklenmesi sırasında anahtarınız başka kişilerin eline geçebilir.

En doğru yaklaşım, gizli bilgileri uygulama kodundan ayırarak ortam değişkenlerinde saklamaktır.

.env dosyası oluşturma

Projenizin kök dizininde .env isimli bir dosya oluşturun ve aşağıdaki değişkenleri tanımlayın:

OPENAI_API_KEY=sk-your-secret-api-key

OPENAI_MODEL=your-available-model-id

Buradaki örnek değerleri kendi API anahtarınız ve erişiminizin bulunduğu model kimliğiyle değiştirmelisiniz.

PHP ile .env dosyasını yüklemek

PHP projelerinde ortam değişkenlerini yönetmek için yaygın olarak kullanılan vlucas/phpdotenv paketinden yararlanabilirsiniz.

Composer kurulumu:

composer require vlucas/phpdotenv

Uygulamanızın başlangıç dosyasına aşağıdaki kodu ekleyin:

require_once __DIR__ . '/../vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__));

$dotenv->load();

API anahtarına artık şu şekilde erişebilirsiniz:

$apiKey = $_ENV['OPENAI_API_KEY'] ?? null;

Gizli bilgilerin Git deposuna gönderilmesini önlemek için .gitignore dosyanıza aşağıdaki satırı ekleyin:

.env

API anahtarını HTML, JavaScript veya tarayıcıya gönderilen herhangi bir dosyada saklamayın. API istekleri sunucu tarafındaki PHP kodunuz üzerinden yapılmalıdır. Mümkünse .env dosyasını web kök dizininin dışında tutun.

5. PHP ile Sohbet Geçmişi ve Context Yönetimi

Bir chatbot'un kullanışlı olabilmesi için yalnızca son kullanıcı mesajını yanıtlaması yeterli değildir. Kullanıcının önceki mesajlarına atıfta bulunduğu durumlarda sistemin konuşma bağlamını koruması gerekir.

Responses API ile mesaj geçmişi gönderme

OpenAI Responses API içerisinde input alanına mesaj dizisi gönderebilirsiniz. Böylece önceki kullanıcı mesajları ve asistan yanıtları yeni isteğin bağlamına dahil edilebilir.

Örnek mesaj dizisi:

$messages = [

['role' => 'user', 'content' => 'PHP nedir?'],

['role' => 'assistant', 'content' => 'PHP sunucu tarafında çalışan bir programlama dilidir.'],

['role' => 'user', 'content' => 'Hangi alanlarda kullanılır?'],

];

API isteği:

$payload = [

'model' => getenv('OPENAI_MODEL'),

'instructions' => 'PHP konusunda uzman bir asistansın.',

'input' => $messages,

'max_output_tokens' => 700,

];

user rolü kullanıcı mesajlarını, assistant rolü ise önceki asistan yanıtlarını temsil eder.

PHP Session ile sohbet geçmişini saklama

Küçük bir chatbot uygulamasında PHP Session kullanmak pratik bir başlangıç yöntemidir.

PHP Session örneği:

session_start();

if (!isset($_SESSION['messages'])) {

$_SESSION['messages'] = [];

}

$userMessage = trim($_POST['message'] ?? '');

if ($userMessage === '') {

http_response_code(422);

exit('Mesaj boş olamaz.');

}

$_SESSION['messages'][] = [

'role' => 'user',

'content' => $userMessage,

];

$_SESSION['messages'] = array_slice($_SESSION['messages'], -10);

API isteğinden sonra asistan yanıtını da geçmişe ekleyebilirsiniz:

$_SESSION['messages'][] = [

'role' => 'assistant',

'content' => $assistantResponse,

];

Bu yöntem küçük uygulamalarda kullanılabilir. Kullanıcı hesapları, kalıcı sohbet geçmişi veya birden fazla cihazdan erişim gerekiyorsa veritabanı kullanmanız daha doğru olacaktır.

Daha gelişmiş uygulamalarda Responses API'nin previous_response_id özelliği de kullanılabilir. Ayrıntılar için OpenAI Conversation State dokümantasyonunu inceleyebilirsiniz.

6. PHP ile Tekrar Kullanılabilir OpenAIClient Sınıfı Geliştirme

API bağlantısını her projede yeniden yazmak yerine tekrar kullanılabilir bir PHP sınıfında toplamak daha sürdürülebilir bir yaklaşımdır. Böylece farklı uygulamalarda aynı bağlantı mantığını kullanabilir, hata yönetimini tek noktadan gerçekleştirebilirsiniz.

Örneğin OpenAIClient.php isminde bir dosya oluşturabilir ve API isteklerini bu sınıf üzerinden yönetebilirsiniz.

OpenAIClient.php – Temel sınıf yapısı:

final class OpenAIClient

{

private string $apiKey;

private string $model;

private string $endpoint = 'https://api.openai.com/v1/responses';

public function __construct(string $apiKey, string $model)

{

if ($apiKey === '' || $model === '') {

throw new InvalidArgumentException('API yapılandırması eksik.');

}

if (!function_exists('curl_init')) {

throw new RuntimeException('PHP cURL eklentisi etkin değil.');

}

$this->apiKey = $apiKey;

$this->model = $model;

}

public function chat(array $messages): array

{

$payload = [

'model' => $this->model,

'instructions' => 'Türkçe yanıt veren teknik bir yazılım asistanısın.',

'input' => $messages,

'max_output_tokens' => 1000,

];

$ch = curl_init($this->endpoint);

curl_setopt_array($ch, [

CURLOPT_POST => true,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_HTTPHEADER => [

'Content-Type: application/json',

'Authorization: Bearer ' . $this->apiKey,

],

CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),

CURLOPT_CONNECTTIMEOUT => 10,

CURLOPT_TIMEOUT => 60,

]);

$response = curl_exec($ch);

$statusCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);

$error = curl_error($ch);

curl_close($ch);

if ($response === false) {

throw new RuntimeException('Bağlantı hatası: ' . $error);

}

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);

if ($statusCode < 200 || $statusCode >= 300) {

$message = $data['error']['message'] ?? 'API isteği başarısız.';

throw new RuntimeException($message, $statusCode);

}

$texts = [];

foreach ($data['output'] ?? [] as $item) {

if (($item['type'] ?? '') !== 'message') {

continue;

}

foreach ($item['content'] ?? [] as $content) {

if (($content['type'] ?? '') === 'output_text') {

$texts[] = $content['text'] ?? '';

}

}

}

return [

'text' => implode("\n", $texts),

'usage' => $data['usage'] ?? [],

'response_id' => $data['id'] ?? null,

];

}

}

Bu sınıf temel API bağlantısını ve yanıt ayrıştırma işlemini tek bir noktada toplar. Üretim ortamında buna sınırlı yeniden deneme, ayrıntılı loglama, istek zaman aşımı yönetimi ve kullanıcı bazlı kullanım limitleri de eklenmelidir.

7. PHP ile AI Destekli Ürün Açıklaması Üretme

OpenAI API yalnızca chatbot geliştirmek için kullanılmaz. E-ticaret uygulamalarında ürün açıklaması, SEO metni ve içerik taslakları oluşturmak için de kullanılabilir.

Örnek olarak bir ürünün adı, kategorisi ve teknik özelliklerini modele göndererek Türkçe bir ürün açıklaması oluşturabiliriz.

Örnek ürün verisi:

$product = [

'name' => 'Kablosuz Bluetooth Kulaklık',

'category' => 'Elektronik',

'features' => [

'Bluetooth 5.3',

'30 saat pil ömrü',

'USB-C şarj',

'Dokunmatik kontrol',

],

];

Ürün açıklaması oluşturmak için prompt:

$prompt = sprintf(

"Aşağıdaki ürün için Türkçe e-ticaret açıklaması hazırla.\nÜrün: %s\nKategori: %s\nÖzellikler: %s\n100-150 kelime yaz. Verilmeyen teknik özellikleri uydurma.",

$product['name'],

$product['category'],

implode(', ', $product['features'])

);

API çağrısı:

$result = $client->chat([

['role' => 'user', 'content' => $prompt],

]);

echo htmlspecialchars($result['text'], ENT_QUOTES, 'UTF-8');

Aynı yaklaşımı blog yazısı taslakları, müşteri destek sistemleri, SEO meta açıklamaları ve kullanıcı yorumlarının sınıflandırılması gibi farklı alanlarda değerlendirebilirsiniz.

Modelin ürettiği bilgileri doğrudan yayımlamak yerine doğrulama ve editör kontrolünden geçirmek önemlidir. Özellikle ürün özellikleri, fiyatlar ve teknik veriler gibi alanlarda modelin yalnızca sağladığınız bilgilere dayanmasını sağlayın.

8. OpenAI API Hataları ve 429 Rate Limit Yönetimi

API entegrasyonlarında her isteğin başarılı olacağını varsaymak doğru değildir. Bağlantı sorunları, hatalı API anahtarı, yetersiz kredi veya istek yoğunluğu nedeniyle çeşitli hatalar oluşabilir.

429 Too Many Requests hatası nedir?

429 hatası, API isteklerinizin hız veya kullanım sınırlarına takıldığını gösterir. Ancak her 429 hatası aynı sebepten kaynaklanmaz. Bazı durumlarda istek sıklığı sınırı aşılırken bazı durumlarda hesap kotası veya kredi yetersizliği söz konusu olabilir.

Rate limit aşımında istek sıklığını azaltmalı ve API yanıtındaki Retry-After başlığını dikkate almalısınız. Kredi veya kullanım kotası tükenmişse faturalandırma ayarlarını kontrol etmelisiniz.

Retry mekanizması nasıl çalışır?

• Geçici sunucu hatalarında sınırlı yeniden deneme yapın.

• Retry-After başlığı varsa belirtilen süreyi dikkate alın.

• Exponential backoff yöntemi kullanın.

• Yetkilendirme ve kredi hatalarını tekrar tekrar denemeyin.

• Hata ayrıntılarını güvenli şekilde loglayın.

Ayrıntılı bilgi için OpenAI API Error Codes ve Rate Limits dokümantasyonlarını inceleyebilirsiniz.

9. PHP Projeleri İçin Doğru OpenAI Modeli Nasıl Seçilir?

Model seçimi uygulamanızın yanıt kalitesini, hızını ve API maliyetini etkiler. Her proje için en güçlü modeli kullanmanız gerekmez. Basit metin sınıflandırma işlemleriyle karmaşık kod analizi görevlerinin ihtiyaçları aynı değildir.

Model seçerken şu kriterleri değerlendirin:

• Yanıt kalitesi ve görev başarısı.

• Girdi ve çıktı token maliyeti.

• Yanıt süresi.

• Bağlam uzunluğu.

• Görevin karmaşıklığı.

• API hesabınızın model erişimi.

Yeni bir projeye başlarken güncel model kataloğunu inceleyin ve uygulamanızın ihtiyaçlarına göre seçim yapın. Eski model isimlerine bağlı kalmak yerine aktif olarak desteklenen modelleri tercih edin.

OpenAI Model Kataloğu

10. OpenAI API Maliyeti Nasıl Hesaplanır?

API maliyetini hesaplarken iki temel değeri dikkate almalısınız:

• Input tokens: Modele gönderdiğiniz talimatlar, mesajlar ve bağlam.

• Output tokens: Modelin oluşturduğu yanıt.

Toplam maliyet, girdi ve çıktı token miktarlarının ilgili modelin bir milyon token başına fiyatlarıyla çarpılmasıyla hesaplanır.

Hesaplama formülü:

Toplam maliyet = (Girdi tokenı × Girdi fiyatı + Çıktı tokenı × Çıktı fiyatı) / 1.000.000

Fiyatlar kullanılan modele ve işlem türüne göre değişir. Bu nedenle sabit fiyatları uygulama koduna gömmek yerine güncel fiyatlandırmayı OpenAI platformundan takip edin.

OpenAI API Pricing

11. PHP ile OpenAI API Entegrasyonunda Güvenlik Önerileri

Bir yapay zekâ entegrasyonu yalnızca API'ye bağlanmaktan ibaret değildir. Özellikle kullanıcıların doğrudan mesaj gönderebildiği uygulamalarda güvenlik ve maliyet kontrolü birlikte ele alınmalıdır.

• API anahtarını yalnızca sunucu tarafında saklayın.

• Kullanıcı başına istek ve token limiti belirleyin.

• Gelen mesajların uzunluğunu kontrol edin.

• HTML çıktısını XSS saldırılarına karşı güvenli işleyin.

• Sohbet geçmişinin sınırsız büyümesini engelleyin.

• Hata mesajlarında gizli bilgileri kullanıcıya göstermeyin.

• API kullanımını ve maliyetini takip edin.

• CSRF koruması ve oturum güvenliği uygulayın.

• API anahtarınızı düzenli olarak gözden geçirin ve gerektiğinde yenileyin.

Sık Sorulan Sorular

OpenAI API Türkçe metinlerde fazla token tüketir mi?

Türkçe metinlerin token tüketimi İngilizceyle birebir aynı değildir. Kelimelerin yapısı, ekler, karakter dizileri ve noktalama işaretleri token sayısını etkileyebilir. Gerçek tüketimi API yanıtındaki usage alanından takip edebilirsiniz.

ChatGPT API ücretsiz mi?

OpenAI API kullanımını ücretsiz ve sınırsız kabul etmemelisiniz. API ücretleri seçilen modele ve girdi ile çıktı token miktarına göre hesaplanır. Hesabınızdaki güncel kredi ve faturalandırma koşullarını OpenAI Platform üzerinden kontrol edebilirsiniz.

PHP ile ChatGPT API kullanmak için Composer gerekli mi?

Hayır. PHP'nin yerleşik cURL ve JSON özellikleriyle API isteği gönderebilirsiniz. Ancak .env yönetimi için vlucas/phpdotenv gibi Composer paketlerinden yararlanabilirsiniz.

PHP ile chatbot geliştirmek zor mu?

Temel bir chatbot geliştirmek için PHP, cURL ve JSON bilgisi yeterlidir. Üretim ortamında ise kullanıcı yönetimi, sohbet geçmişi, güvenlik, rate limit ve maliyet kontrolü gibi konular da ele alınmalıdır.

API anahtarını JavaScript içerisinde kullanabilir miyim?

Hayır. API anahtarını tarayıcıya göndermek güvenli değildir. JavaScript arayüzü mesajı PHP backend'inize iletmeli, PHP backend'i ise OpenAI API ile iletişim kurmalıdır.

ChatGPT API ile kendi yapay zekâ modelimi geliştirebilir miyim?

OpenAI API kullanarak kendi modelinizi sıfırdan eğitmiş olmazsınız. Mevcut modelleri uygulamanıza entegre edebilir, talimatlar ve bağlam üzerinden belirli görevleri yerine getiren yapay zekâ destekli sistemler oluşturabilirsiniz.

Sonuç: PHP Uygulamalarınıza Yapay Zekâ Özellikleri Ekleyin

PHP ile OpenAI API entegrasyonu, mevcut web uygulamalarınıza yeni özellikler kazandırmanın pratik yollarından biridir. Basit bir cURL isteğiyle başlayabilir, API iletişimini tekrar kullanılabilir bir PHP sınıfına dönüştürebilir ve bu altyapıyı chatbot, içerik üretimi veya otomasyon sistemlerinde kullanabilirsiniz.

Güvenli yapılandırma, doğru model seçimi, sohbet geçmişi yönetimi ve maliyet kontrolü başarılı bir entegrasyonun temel bileşenleridir.

UNQSOFT olarak yazılım geliştirme süreçlerinde önemli gördüğümüz noktalardan biri, yeni teknolojileri yalnızca kullanmak değil, onları güvenli ve sürdürülebilir yazılım mimarileri içerisinde değerlendirmektir.

Küçük bir PHP uygulamasıyla başlayın, gerçek kullanım verilerini takip edin ve ihtiyaçlarınıza göre sisteminizi geliştirin.

Resmî Teknik Kaynaklar

• OpenAI API Dokümantasyonu

• OpenAI Quickstart

• OpenAI Model Kataloğu

• OpenAI API Fiyatlandırması

• Conversation State

• API Rate Limits