Perplexity API Anahtarı Nasıl Alınır ve İlk Sonar İsteğinizi Yapın

Bir Perplexity API anahtarı, api.perplexity.ai adresine gönderdiğiniz her istekle birlikte gönderdiğiniz kimlik bilgisidir. Projenizi tanımlar, ön ödemeli kredi bakiyenizden düşer ve oran sınırı kademenizi belirler. Daha önce hiç kullanmadıysanız, API anahtarı nedir hakkındaki başlangıç kılavuzumuz temel bilgileri kapsar. Bu kılavuz, Perplexity'ye özgü kısmı ele alır: hesap oluşturma, kredi ekleme, anahtar oluşturma ve curl, Python ve Apidog'dan ilk doğruluk temelinde Sonar isteğinizi gönderme.

Başlamadan önce bir zamanlama notu. Perplexity, Sonar'ı Agent API'sine taşıdı ve resmi hızlı başlangıç artık orayı işaret ediyor. Eski Sonar sohbet tamamlama uç noktası 27 Eylül 2026'ya kadar çalışmaya devam edecek, sonra kullanımdan kaldırılacak. Aşağıdaki her örnek, eski kodu sürdürüyorsanız eski forma kısa bir notla birlikte mevcut uç noktayı kullanır.

Başlamadan önce ihtiyacınız olanlar

• Bir Perplexity hesabı. Google, Apple, SSO veya şifresiz e-posta ile giriş hepsi çalışır ve e-posta adresiyle aynı hesaba yönlendirilirler.
• Bir ödeme kartı. API aboneliksiz kullandıkça öde esasına göre çalışır, ancak kredi bakiyeniz sıfıra ulaştığında istekler başarısız olur.
• İlk istek için curl veya Python 3.9+
• Anahtarı yerel bir gizli olarak saklamak ve isteği tekrarlanabilir bir test olarak kaydetmek isterseniz Apidog.

Adım 1: API konsoluna giriş yapın ve bir proje oluşturun

console.perplexity.ai adresine gidin ve bir giriş yöntemi seçin. Giriş yapmak bir Perplexity hesabı oluşturur, ancak bir API projesi oluşturmaz. İlk ziyaretinizde, anahtarlar projelere özel olduğundan, bir anahtar oluşturmadan önce bir proje oluşturmanız veya bir projeye katılmanız için kurulum sihirbazı sizi yönlendirir.

Sol kenar çubuğunda **Ayarlar**'ı açın ve kuruluşunuzun adını, adresini ve vergi bilgilerini doldurun; bunlar faturalarınızda yer alacaktır. Şirketinizin zaten bir projesi varsa, ikinci bir tane oluşturmak yerine bir yöneticiden sizi o projeye eklemesini isteyin. Ayrı projeler ayrı kredi bakiyeleri ve anahtarlar alır, bu da bir üretim uygulamasını bir deneyden izole etmek için kullanışlıdır.

Adım 2: Bir ödeme yöntemi ve kredi ekleyin

Faturalandırma sayfasını açın ve bir kart ekleyin. Belgelerde belirtildiği gibi, bir ödeme yöntemi eklemek kartı ücretlendirmez; gelecekteki kullanım için ayrıntıları saklar. Ardından kredi satın alın. Bakiye, modele göre kullanım dökümleri ve fatura geçmişi bu sayfada yer alır.

Burada iki ayrıntı önemlidir. API, ön ödemeli kredilerden faturalandırır ve bakiye biterse anahtarlarınız yükleme yapana kadar engellenir. Belgeler bu hatayı 402 değil, 401 olarak tanımlar, bu nedenle kredisiz bir uygulama ilk bakışta bir kimlik doğrulama hatası gibi görünür. Ve **Otomatik yeniden yükle**'nin yanında, bakiye belirlediğiniz bir eşiğin altına düştüğünde konsolun otomatik olarak kredi eklemesini sağlamak için **Tercihleri değiştir**'e tıklayın. Üretim ortamına geçmeden önce bunu açın.

Belgelerde minimum satın alma miktarı yayınlanmamıştır, bu nedenle faturalandırma sayfasının size gösterdiğine göre hareket edin. Oran limitlerinizi belirleyen kullanım katmanınız, hesabın ömrü boyunca satın alınan birikimli kredilere dayanır, mevcut bakiyeye değil.

Adım 3: API anahtarını oluşturun

Konsoldaki API Anahtarları sayfasını açın ve bir anahtar oluşturun. Anahtara dev-laptop veya prod-search-worker gibi açıklayıcı bir ad verin. Oluşturulduktan sonra, anahtarları birbirinden ayırmanın tek yolu addır, çünkü tam değeri bir kez gösterilir ve bir daha alınamaz. Hemen kopyalayın.

Anahtarı hiçbir zaman kodun içine değil, bir ortam değişkenine yerleştirin:

export PERPLEXITY_API_KEY="pplx-your-key-here"

Windows'ta, setx PERPLEXITY_API_KEY "pplx-your-key-here" komutunu kullanın ve yeni bir terminal açın.

Bir proje içinde birden fazla anahtar oluşturabilirsiniz, bu nedenle her ortam ve her servis için bir tane oluşturun. Bir anahtarı iptal etmek kalıcıdır, bu bir anahtar sızdığında istediğiniz şeydir. Bir anahtarın bir depoya sızıp sızmadığından emin değilseniz, anahtarı döndürmeden önce git geçmişiniz üzerinde bir gizli tarayıcı çalıştırın.

Adım 4: İlk Sonar isteğinizi yapın

Mevcut uç nokta `POST https://api.perplexity.ai/v1/agent` şeklindedir. Kimlik doğrulama standart bir taşıyıcı başlığıdır, `Authorization: Bearer $PERPLEXITY_API_KEY`. İstek gövdesi bir `model` ve bir `input` dizesi alır. Bu uç noktadaki Sonar model kimliği `perplexity/sonar`'dır ve `web_search` aracını eklemek, canlı web'de arama yapmasını ve kaynakları eklemesini söyler.

Zamanla değişen gerçek bir cevabı olan bir şey sorun:

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity/sonar",
    "input": "Which Node.js release line is currently Active LTS, and when does it reach end of life?",
    "tools": [{ "type": "web_search" }]
  }' | jq

Yanıt, düz metin olarak cevabı içeren `output_text`'i ve modelin attığı her adım için bir öğeye sahip bir `output` dizisini taşır. `message` öğesi cevabı tutar; `search_results` öğesi okuduğu sayfaları listeler, her biri bir `url`, `title`, `snippet` ve `date` içerir. `usage` nesnesi token sayılarını ve maliyetini rapor eder. `completed` durumu, çalışmanın bittiği anlamına gelir.

Resmi SDK ile Python'da aynı istek:

pip install perplexityai

from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY from the environment

response = client.responses.create(
    model="perplexity/sonar",
    input="Which Node.js release line is currently Active LTS, and when does it reach end of life?",
    tools=[{"type": "web_search"}],
)

print(response.output_text)

OpenAI SDK'sını tercih ediyorsanız, `base_url="https://api.perplexity.ai/v1"` olarak ayarlayın ve `client.responses.create()`'i aynı argümanlarla çağırın. SDK bunu Perplexity'nin bir takma ad olarak kabul ettiği `/v1/responses` adresine yönlendirir. Ön ayarlar (`fast`, `low`, `medium`, `high`, `xhigh`), sizin için bir model, token bütçeleri ve araçları paketler; OpenAI SDK'sında bunları `extra_body` aracılığıyla iletirsiniz.

Eski sohbet tamamlama formundaysanız

Eski kod, `sonar`, `sonar-pro`, `sonar-reasoning-pro` veya `sonar-deep-research` model kimlikleriyle `messages`'ı `https://api.perplexity.ai/v1/sonar` adresine gönderir ve `choices[0].message.content`'i okur. Bu form 27 Eylül 2026'ya kadar çalışır. Geçiş kılavuzu, `sonar`'ı `perplexity/sonar`'a, `sonar-pro`'yu `low` ön ayarıyla `perplexity/sonar`'a ve derin araştırmayı `high` ön ayarına eşler. `search_domain_filter` ve `search_recency_filter` seçenekleri, `filters` nesnesi olarak `web_search` aracı içine taşınır.

Adım 5: Anahtarı saklayın ve isteği Apidog'a kaydedin

Bir kez çalışan bir curl bir test değildir. Anahtarın bulutta kalmaması ve isteğin isteğe bağlı olarak çalışması için Apidog'da kullandığımız kurulum şöyledir.

**Bir ortam oluşturun.** `Perplexity` adlı bir ortam oluşturun. Bu ortamda iki değişken olsun: `base_url` ortak bir değer olarak `https://api.perplexity.ai`'ye ayarlanmış ve `PERPLEXITY_API_KEY` ortak değer yer tutucu olarak bırakılmış ve gerçek anahtar yalnızca **yerel değerde** olacak şekilde. Yerel değerler istemcinizin önbelleğinde yaşar ve hiçbir zaman takım arkadaşlarıyla senkronize olmaz, asıl amaç da budur. Apidog'daki ortamlar ve gizli değişkenler kılavuzumuz, paylaşılan ve yerel ayrımına daha derinlemesine değinir.

**İsteği oluşturun.** Yeni istek, `POST {{base_url}}/v1/agent`. Bir `Authorization: Bearer {{PERPLEXITY_API_KEY}}` başlığı ekleyin, gövde türünü JSON olarak ayarlayın ve yukarıdaki curl ile aynı gövdeyi yapıştırın. `Perplexity` ortamını seçin ve Gönder'e tıklayın. Yanıt panelinde `output_text` ve `search_results` bloğunu görmelisiniz.

**Bir teste dönüştürün.** Üç doğrulama ekleyin: durum kodu `200`, `$.status` `completed`'a eşit ve `$.output_text` boş değil. İsteği bir test senaryosuna kaydedin. Artık ekipten herkes projeyi çekebilir, kendi anahtarını yerel değere yapıştırabilir ve kurulumunu tek tıklamayla doğrulayabilir. Anahtarı döndürmek, komut dosyalarında arama yapmak yerine tek bir alanı düzenlemek anlamına gelir.

Henüz yoksa, Apidog'u ücretsiz indirin; ücretsiz plan dört kullanıcıyı kapsar, küçük bir ekibin projeyi paylaşması için yeterlidir.

Oran limitleri ve bir isteğin maliyeti

Agent API üzerindeki oran limitleri, kullanım kademenizle ölçeklenir ve kademeler, oran limitleri sayfasına göre hesap ömrü boyunca yapılan toplam kredi satın alımlarına göre belirlenir:

Limitler bir sızdıran kova algoritması kullanır, bu nedenle limite kadar kısa süreli ani artışlar geçer. Aşıldığında API, `Retry-After` başlığıyla birlikte bir `429` döndürür ve reddedilen istekler faturalandırılmaz. Mevcut kademeniz, konsolun Fiyatlandırma sayfasında kullanım kademeleri sekmesi altında gösterilir.

Fiyatlandırma hakkında burada bir paragraf yeterlidir. Fiyatlandırma sayfası, Agent API'deki `perplexity/sonar`'ı, milyon giriş tokeni başına 0,25 dolar ve milyon çıkış tokeni başına 2,50 dolar, ayrıca her `web_search` çağrısı için 0,0025 dolar olarak listeler. Eski Sonar sohbet tamamlama modelleri farklı faturalandırılır: `sonar`, milyon token giriş ve çıkış başına 1 dolar, ayrıca arama bağlamı boyutuna bağlı olarak bin istek başına 5 ila 12 dolar. Tam döküm ve Pro-hesap bakış açısı için Perplexity API kılavuzumuza bakın.

Yaygın hatalar ve bunları düzeltme yolları

**401 Yetkilendirilmemiş.** Olasılık sırasına göre üç neden: başlık yanlış (`Authorization: Bearer` olmalı ve kabuk değişkeni aynı terminalde dışa aktarılmış olmalı), anahtar iptal edildi veya kredi bakiyesi sıfırda. Herhangi bir şeyi yeniden oluşturmadan önce faturalandırma sayfasını kontrol edin. Python SDK'sı bunun için `AuthenticationError` hatası verir.

**400 Hatalı İstek.** Genellikle eski formattaki bir gövdenin yeni uç noktaya gönderilmesi: `input` yerine `messages` veya `/v1/agent` üzerinde boş bir `sonar-pro` model kimliği. SDK bunu `ValidationError` olarak ortaya çıkarır.

**404 Bulunamadı.** Yol yanlış. `/v1/agent` Agent API'dir ve `/v1/sonar` eski sohbet tamamlama uç noktasıdır; belgeler başka hiçbir şey listelemez.

**429 Çok Fazla İstek.** Kademenizin limitine ulaştınız. `Retry-After`'ı okuyun, o kadar bekleyin, ardından üstel geri çekilme ve titreme ile yeniden deneyin. Sürekli iş hacmine ihtiyacınız varsa kredi satın almak kademenizi yükseltir. SDK'nın hata işleme kılavuzu `RateLimitError` desenini gösterir.

**500 veya 503.** Sunucu tarafı. Bir gecikmeyle yeniden deneyin; sıkı yeniden deneme döngüleri oran sınırlamasını daha da kötüleştirir.

SSS

Ücretsiz bir Perplexity API anahtarı var mı?

Belgelenmiş ücretsiz bir katman yoktur. API, ön ödemeli kredi bakiyesinden kullandıkça öde esasına göre çalışır ve kredisiz bir proje engellenir. `perplexity/sonar` ile yapılan ilk isteğin ve bir web aramasının maliyeti bir sentin çok küçük bir kısmıdır, bu nedenle küçük bir yükleme çok sayıda testi karşılar.

İlk istek için hangi model kimliğini kullanmalıyım?

`/v1/agent` üzerinde `web_search` aracıyla `perplexity/sonar` kullanın. Bu, en düşük maliyetli temel seçenek olup, geçiş kılavuzunun eski `sonar` ve `sonar-pro` kimliklerini eşleştirdiği seçenektir. Perplexity'nin sizin için modeli ve arama bütçesini seçmesini istediğinizde `low` veya `medium` gibi bir ön ayara geçin.

Sadece arama sonuçları istiyorsam Agent API'ye ihtiyacım var mı?

Hayır. Ayrı bir Arama API'si, bir model çalıştırmadan sıralanmış sonuçlar döndürür; bu, sayfaları kendi hattınıza beslerken daha ucuzdur. Perplexity Arama API'si kılavuzumuz, istek şeklini ve filtreleri gösterir.

Kesinti olmadan bir anahtarı nasıl döndürürüm?

Aynı projede ikinci bir anahtar oluşturun, eskisinin kullanıldığı her yere dağıtın, yeni anahtar üzerindeki trafiği onaylayın, ardından eskiyi iptal edin. İptal kalıcıdır, bu nedenle önce her tüketiciyi güncelleyin. Perplexity ayrıca döndürmeyi otomatikleştirmek isterseniz `/generate_auth_token` ve `/revoke_auth_token` uç noktalarını da sunar.

Özet

Giriş yapın, bir proje oluşturun, kredi satın alın, bir anahtar oluşturun, `/v1/agent` adresine `perplexity/sonar` ile bir istek gönderin. Yolun tamamı budur. Anahtarı Apidog'da yerel bir değer olarak saklayın ve isteği bir test olarak kaydedin, böylece ekibinizdeki bir sonraki kişi dakikalar içinde doğrulanabilir bir kurulum elde eder. Sohbet tamamlama uç noktasında hala kodunuz varsa, 27 Eylül 2026'dan önce onu taşıyın.