WordPress AI Client API Nedir ve Nasıl Kullanılır?

WordPress AI Client API, WordPress 7.0 ile birlikte core’a giren, sağlayıcıdan bağımsız (provider-agnostic) bir PHP katmanıdır. Eklentiler, tek bir wp_ai_client_prompt() çağrısıyla OpenAI, Anthropic veya Google Gemini gibi modellere bağlanır. Yanıtlar normalize şekilde döner; eklenti tarafı modeli değil, sözleşmeyi tanır. Bu yazı, sözleşmenin tam yüzeyini, gerçek kod örneklerini ve sahada karşılaşılan hataları derliyor.

Temel giriş noktası wp_ai_client_prompt() fonksiyonudur ve bir WP_AI_Client_Prompt_Builder döner. Bu builder, akıcı (fluent) bir API ile prompt’u özelleştirir ve generate_text(), generate_image() gibi üretim metotlarıyla sonucu üretir. Eklenti geliştiricisi olarak işiniz, “ne istiyorum” ve “nasıl istiyorum”u tanımlamaktır. Hangi modelin çalışacağına ve API anahtarını kime verdiğinize WordPress karar verir.

Resmi tanıtım yazısına göre bu katman iki bileşenden oluşur: alttaki wordpress/php-ai-client (PHP AI Client) sağlayıcı iletişimini yönetir, üstündeki WordPress sarmalayıcısı ise snake_case metot isimleri, WP_Error dönüşleri ve HTTP API entegrasyonu sağlar. Bu ayrım, üst katman geliştiricisinin camelCase istisna yönetimiyle değil, klasik WordPress kod sözleşmesiyle çalışmasını mümkün kılar.

WordPress 7.0’da Yapay Zeka Katmanı: AI Client API’nin Sözleşmesi

WordPress 7.0 sürümüyle birlikte AI Client, core’a yerleşik gelir. Bu, AI özelliği geliştirmenin “eklentiyle uğraş” dönemini kapatır. Core’a giren şey sadece bir sınıf değildir; kararlı bir sözleşme (interface), bir registry ve bir HTTP katmanı birlikte gelir.

Sözleşmenin omurgası şu ilkeye dayanır: eklenti “ne” istediğini söyler, “kime” sorusunu WordPress halleder. Bu ilke, üç resmi sağlayıcı eklentisinin varlığıyla pratikte çalışır. Her sağlayıcı kendi API anahtarını yönetir; eklenti tarafı bu anahtarlarla hiç ilgilenmez. Kimlik bilgileri, Settings > Connectors ekranından girilir ve otomatik olarak registry’ye bağlanır.

Sözleşme şu metotları garanti eder:

• with_text(), with_file(), with_history() — prompt’un içeriğini kurar
• using_temperature(), using_max_tokens(), using_top_p(), using_top_k(), using_stop_sequences() — üretim parametrelerini ayarlar
• using_system_instruction() — sistem talimatını (system prompt) ekler
• using_model_preference() — tercih edilen model sırasını bildirir
• as_json_response() — JSON şeması ile yapılandırılmış çıktı ister
• as_output_modalities() — metin, görsel, ses veya video çıktı türlerini belirler
• generate_text(), generate_texts( $n ), generate_image(), generate_images( $n ), generate_speech(), convert_text_to_speech(), generate_video() — üretim uç noktaları
• is_supported_for_text_generation(), is_supported_for_image_generation() vb. — gerçek API çağrısı yapmadan özellik tespiti

Bu liste, WP_AI_Client_Prompt_Builder sınıfının public yüzeyidir. PHP AI Client’in camelCase metotlarına karşılık gelen snake_case metotlar olarak yazılmıştır. Eklenti geliştiricisi bu listeyi referans alır.

Bu noktada, AI Client’in Connectors API ile nasıl konuştuğunu anlamak önemlidir; kimlik bilgisi yönetimi bu katman üzerinden akar.

İstemci Mimarisi: Provider Sınıfları ve Registry Nasıl Çalışır?

AI Client iki katmandan oluşur. Alttaki katman, PHP AI Client paketidir; PHP topluluğunun başka projelerde de kullanabileceği sağlayıcı-agnostik bir SDK’dır. Üstteki katman, WordPress’e özgü sarmalayıcıdır. Bu sarmalayıcı, PHP AI Client’in camelCase API’sini WordPress’in snake_case dünyasına taşır, exception’ları WP_Error‘a çevirir ve WordPress HTTP API’si ile PSR uyumlu istemci arasında köprü kurar.

Registry tarafında işler şöyle akar:

1. Bir sağlayıcı eklentisi yüklendiğinde, provider sınıfı PHP AI Client’in registry’sine kaydolur.

2. Site yöneticisi Settings > Connectors ekranından bu sağlayıcı için API anahtarını girer.

3. Eklenti geliştiricisi wp_ai_client_prompt( '...' ) çağırır.

4. Builder, prompt gereksinimlerine uyan ilk uygun sağlayıcıyı seçer (veya using_model_preference() ile belirtilen sıraya göre ilk uygun modeli).

5. İstek, HTTP API üzerinden sağlayıcıya gider; yanıt normalize edilerek geri döner.

Bu akışın en önemli sonucu, eklenti kodunun hiçbir zaman belirli bir sağlayıcıya sabit kodlanmaması gerektiğidir. Sözleşme, dağıtılabilir eklentilerin herhangi bir sağlayıcı yapılandırmasıyla çalışmasını garanti eder.

Aşağıdaki tablo, üç resmi sağlayıcının farklılaştığı noktaları özetler:

Tablo, core takımının yayınladığı üç flagship eklentiyi temel alır. Topluluk tarafından geliştirilen ek sağlayıcılar da aynı sözleşmeye uyduğu sürece birlikte çalışır. Provider seçimi ve modellerin nasıl kayıt edildiği konusunda daha fazla ayrıntı, PHP AI Client GitHub deposunda bulunabilir.

Üç Sağlayıcıyı Tek Satırda Değiştirmek: Yapılandırma Örneği

Provider-agnostic yaklaşımın en somut kanıtı, aynı kodun üç farklı sağlayıcıyla hiç değişmeden çalışmasıdır. Aşağıdaki örnek, ürün açıklaması üreten bir eklentinin prompt’unu gösterir:

$result = wp_ai_client_prompt( 'Bu ürün için 60 kelimelik, SEO uyumlu bir Türkçe açıklama yaz.' )
    ->using_temperature( 0.4 )
    ->using_system_instruction( 'Sen deneyimli bir Türk e-ticaret kopyacısısın. Ölçülü, net ve satış odaklı yaz.' )
    ->using_max_tokens( 400 )
    ->as_json_response( array(
        'type'       => 'object',
        'properties' => array(
            'description' => array( 'type' => 'string' ),
            'keywords'    => array( 'type' => 'array', 'items' => array( 'type' => 'string' ) ),
        ),
        'required'   => array( 'description', 'keywords' ),
    ) )
    ->generate_text();

if ( is_wp_error( $result ) ) {
    return $result;
}

$data = json_decode( $result, true );

Bu çağrı, hangi sağlayıcının yapılandırıldığına göre otomatik olarak Anthropic, Google veya OpenAI’a gider. Eğer model tercihi belirlemek isterseniz, using_model_preference() zincirin başında gelir:

$text = wp_ai_client_prompt( 'Yazdığım blog taslağını özetle.' )
    ->using_model_preference(
        'claude-sonnet-4-6',
        'gemini-3.1-pro-preview',
        'gpt-5.4'
    )
    ->using_temperature( 0.2 )
    ->generate_text();

Burada önemli nüans şudur: tercih zorunluluk değildir. Listede olmayan ama prompt’a uygun başka bir model de kullanılabilir. Bu, sitenizde sadece OpenAI yapılandırılmışsa ve listede ilk sırada Claude varsa bile istediğiniz sonucu almanızı sağlar.

Belirli bir modeli zorlamak istiyorsanız, using_model() kullanılır; ancak bu yaklaşım eklentinizi sadece o sağlayıcıyı kurmuş sitelerde çalışır hale getirir. Çoğu senaryo için model tercihi yeterlidir.

Görsel üretimi için sözleşme aynı kalır:

$image = wp_ai_client_prompt( 'Minimal bir WordPress logolu kapak görseli, gradient arka plan' )
    ->using_model_preference( 'gpt-image-1', 'imagen-4', 'gemini-2.5-flash-image' )
    ->as_output_file_type( \WordPress\AiClient\Files\Enums\FileTypeEnum::inline() )
    ->generate_image();

if ( is_wp_error( $image ) ) {
    return $image;
}

$data_uri = $image->getDataUri();

generate_image() çağrısı bir File DTO döner; getDataUri() yöntemiyle doğrudan  etiketine gömülebilir veri elde edersiniz.

Eklentilerin bu sözleşmeyle nasıl yeteneklerini (abilities) tanımladığını görmek isterseniz, Abilities API rehberimizi inceleyebilirsiniz.

Action Scheduler ve Cache: Üretimden Sonra Arka Plan Mekaniği

AI Client, tek seferlik bir HTTP çağrısından ibaret değildir. Üretim sonrası ölçüm ve meta veri yönetimi sözleşmenin parçasıdır. generate_text_result(), generate_image_result() gibi sonuç odaklı metotlar bir GenerativeAiResult döner; bu nesne üç kritik bilgiyi de taşır:

• getTokenUsage() — giriş, çıkış ve varsa “düşünme” (thinking) token sayıları
• getProviderMetadata() — isteği hangi sağlayıcının işlediği
• getModelMetadata() — yanıtı hangi modelin ürettiği

Bu üçlü, REST katmanında rest_ensure_response() ile doğrudan istemciye aktarılabilir. Yani bir eklenti, kendi REST endpoint’inde GenerativeAiResult döndüğünde hata varsa WP_Error ile birlikte anlamlı bir HTTP kodu atanır; başarı durumunda metadata JSON’ın bir parçası olur.

Önbellekleme açısından, prompt sonuçlarını transient API ile önbelleğe almak yaygın bir desendir:

$cache_key = 'ai_summary_' . md5( $post_id . $prompt_version );
$summary   = get_transient( $cache_key );

if ( false === $summary ) {
    $summary = wp_ai_client_prompt( $prompt_text )
        ->generate_text();

    if ( ! is_wp_error( $summary ) ) {
        set_transient( $cache_key, $summary, HOUR_IN_SECONDS );
    }
}

Bu yaklaşım, tekrarlayan prompt çağrılarında token maliyetini düşürür. Ancak hassas içerik için kısa TTL’ler veya önbellek anahtarında prompt versiyonu tutmak önerilir.

Toplu işler için Action Scheduler ile kuyruğa almak yerinde bir seçimdir. Özellikle 50 ürün açıklaması üretilecekse, tek istekte 50 prompt göndermek yerine her ürün için bir as_schedule_single_action() çağrısı zamanlama daha sağlıklıdır. Bu sayede sağlayıcı rate limit’lerine takılmadan iş tamamlanır.

Sık Karşılaşılan 5 Hata ve Çözümleri

Sahada karşılaşılan gerçek hatalar, genelde sözleşmenin “kapı bekçisi” olan is_supported_for_*() metotlarının atlanmasından kaynaklanır. Aşağıdaki senaryolar, GitHub issue’ları ve core.trac tartışmalarından derlendi.

1. “Provider is not configured” — WP_Error kodu: wp_ai_client_provider_not_configured

Eklenti, hiçbir sağlayıcı kurulmamış bir sitede çalışır. Çözüm: UI göstermeden önce is_supported_for_text_generation() ile kontrol edin. Destek yoksa kullanıcıya “AI özelliği için lütfen Settings > Connectors’dan bir sağlayıcı kurun” mesajı gösterin.

2. “Model not found in preference list” — fallback’e düşen prompt beklenen formatta dönmez

using_model_preference() zincirine yanlış model ID’si yazmak (örn. gpt-5 yerine gpt-5.4 yazmak). Çözüm: tercihleri sağlayıcının güncel model kataloğundan doğrulayın; her modelin tam sürüm numarasını kullanın.

3. “JSON schema validation failed”

as_json_response() ile istenen şema, modelin döndüğü JSON ile eşleşmez. Bu genelde model çok yaratıcı (yüksek temperature) olduğunda olur. Çözüm: temperature’ı 0.1–0.3 aralığına indirin ve required alanlarını açıkça tanımlayın.

4. generate_text() WP_Error döner ama get_error_data() boş

Bu genelde transient cache’lenmiş eski bir hata kaydıdır. Çözüm: cache anahtarına sağlayıcı + model bilgisini ekleyin veya transient’i temizleyen bir “AI sıfırla” admin butonu koyun.

5. “Image generation: permission denied” — JS API tarafında

wp.aiClient.prompt() çağrısı frontend’de prompt_ai yetkisi olmayan kullanıcılarda başarısız olur. Çözüm: client-side API tüm kullanıcılara açık değildir; admin-only’dir. Dağıtılabilir bir eklenti yazıyorsanız, kendi REST endpoint’inizi açıp orada current_user_can() ile sıkı kontrol uygulayın.

Bu beş hatanın ortak kökü, özellik tespiti (is_supported_for_*()) yapmadan doğrudan generate_*() çağrısı yapmaktır. Sözleşmenin sağladığı en önemli güvenlik ağı bu metotlardır.

Sonuç: WP AI Client API Projene Değer Katar mı?

WordPress AI Client API, eklenti geliştiricisini sağlayıcı seçiminden, API anahtarı yönetiminden ve HTTP katmanı detaylarından kurtarır. Bu, özellikle dağıtılabilir eklentiler yazanlar için büyük bir pratik kazançtır. Bir eklenti, kullanıcının hangi sağlayıcıyı kurduğunu bilmek zorunda kalmadan çalışır.

Ancak her projeye uygun değildir. Şu durumlarda AI Client API tercih edilir:

• Eklentiniz birden fazla sitede çalışacak ve her sitede farklı sağlayıcı olabilir
• OpenAI/Anthropic arasında geçiş yapmanız gerekiyor veya bu geçişi kullanıcıya bırakmak istiyorsunuz
• Token kullanımı, sağlayıcı metadata’sı gibi denetim bilgilerine ihtiyacınız var

Şu durumlarda ise doğrudan sağlayıcı SDK’sı daha iyi olabilir:

• Sadece tek bir sağlayıcıyla çalışacaksınız ve o sağlayıcıya özel ileri düzey özellikler (fine-tuning, function calling) kullanmanız gerekiyor
• AI Client’in henüz desteklemediği bir modality (örn. realtime audio streaming) gerekli

Sonuç olarak, WordPress 7.0’ın AI Client API’si, WordPress ekosistemini “AI hazır” hale getiren kararlı bir sözleşmedir. Sözleşmeye uyduğunuzda, kullanıcılarınız hangi sağlayıcıyı seçerse seçsin eklentiniz çalışır. Bu, 2026’nın WordPress eklenti geliştirme gerçekliğinde önemli bir rahatlamadır.

Sözleşmenin resmi tanıtım yazısına bakarak her metodun son güncel halini doğrulayabilirsiniz. Eklenti tarafında daha derine inmek için wp-ai-client GitHub deposu iyi bir başlangıç noktasıdır.

—

Bir sonraki adım: Bu makaleyi beğendiyseniz, Abilities API rehberimiz ile WordPress 7.0’ın “yetenek” kavramını keşfedin. Eklenti yazarken AI özelliğini kontrollü şekilde sunmak için tamamlayıcı bir okuma niteliğindedir.

—

Sık Sorulan Sorular

WordPress AI Client API, WordPress 7.0 öncesi sürümlerde çalışır mı?

Hayır, sözleşme 7.0 ile core’a girdi. Ancak 6.x serisi için composer require wordpress/wp-ai-client paketini bağımlılık olarak ekleyerek benzer API’yi kullanabilirsiniz; bu paket kendi PHP SDK altyapısını sağlar. 7.0’a geçişte tek yapmanız gereken AI_Client::prompt() çağrılarını wp_ai_client_prompt() ile değiştirmektir.

AI Client API kullanmak için Composera veya lisans anahtarına ihtiyaç var mı?

Hayır. AI Client, GPL-2.0 lisanslıdır ve core’un parçasıdır. Sağlayıcı API anahtarları ise eklenti sahibinin değil, site yöneticisinin Settings > Connectors ekranından girdiği anahtarlardır. Eklenti kodunuzda hiçbir zaman API anahtarı bulunmamalıdır.

Prompt sonuçları WordPress’in kendi önbelleğinde saklanıyor mu?

Hayır, AI Client kendi başına cache yapmaz. get_transient() / set_transient() ile siz caching stratejinizi kurarsınız. Token maliyetini düşürmek için bu önerilir; hassas veri içinse kısa TTL veya cache’siz çalışmak daha uygundur.

using_model_preference() ile using_model() arasındaki fark tam olarak nedir?

using_model_preference() bir tercih listesi bildirir; listedeki modellerden biri yoksa başka uygun bir modele düşer (fallback). using_model() ise tek bir modeli zorlar; o sağlayıcı kurulu değilse is_supported_for_*() false döner ve UI gizlenmelidir. Çoğu durumda using_model_preference() daha esnek ve önerilen yaklaşımdır.

Multilingual projelerde Türkçe promptlar nasıl daha iyi sonuç verir?

using_system_instruction() ile “Sen Türkçe yazıyorsun, XXXXX” gibi bir sistem talimatı verin. Temperature’ı 0.3–0.5 aralığında tutun; çok düşük sıcaklık yaratıcılığı, çok yüksek sıcaklık tutarlılığı bozar. JSON şema istiyorsanız required alanlarını açıkça tanımlamak, modelin alanları atlamasını önler.

AI Client API, eklentimin WordPress.org eklenti dizinine kabul edilmesini etkiler mi?

Doğrudan etkilemez. Ancak WordPress.org eklenti inceleme ekibi, kullanıcı verisini izinsiz dış servislere gönderen kodlara dikkat eder. wp_ai_client_prompt() çağrısının hangi koşullarda tetiklendiğini, kullanıcıya açıkça bildiren bir onay mekanizması eklemek inceleme sürecinde sorunsuz geçmenizi sağlar.