مفتاح Perplexity API هو بيانات الاعتماد التي ترسلها مع كل طلب إلى api.perplexity.ai. يحدد هذا المفتاح مشروعك، ويخصم من رصيدك الائتماني المدفوع مسبقًا، ويحدد فئة حد المعدل الخاص بك. إذا لم تتعامل مع أحد من قبل، فإن دليلنا التمهيدي حول ما هو مفتاح API يغطي الأساسيات. يغطي هذا الدليل الجزء الخاص بـ Perplexity: إنشاء الحساب، إضافة الأرصدة، إنشاء المفتاح، وإرسال أول طلب Sonar قائم على البيانات من curl و Python و Apidog.
ملاحظة توقيت واحدة قبل أن تبدأ. نقلت Perplexity خدمة Sonar إلى Agent API الخاص بها، ويشير دليل البدء السريع الرسمي الآن إلى هناك. ستستمر نقطة نهاية Sonar القديمة لإكمال المحادثات في العمل حتى 27 سبتمبر 2026، ثم يتم إيقافها. يستخدم كل مثال أدناه نقطة النهاية الحالية، مع ملاحظة قصيرة حول النموذج القديم في حال كنت تحتفظ برمز قديم.
ما تحتاجه قبل البدء
- حساب Perplexity. يعمل تسجيل الدخول عبر Google أو Apple أو SSO أو البريد الإلكتروني بدون كلمة مرور، وتؤدي جميعها إلى نفس الحساب باستخدام عنوان البريد الإلكتروني.
- بطاقة دفع. واجهة برمجة التطبيقات (API) تعمل بنظام الدفع حسب الاستخدام بدون اشتراك، ولكن الطلبات تفشل بمجرد أن يصل رصيدك الائتماني إلى الصفر.
- curl أو Python 3.9+ للطلب الأول.
- Apidog إذا كنت تريد تخزين المفتاح كسِر محلي وحفظ الطلب كاختبار قابل للتكرار.
الخطوة 1: تسجيل الدخول إلى وحدة تحكم API وإنشاء مشروع
انتقل إلى console.perplexity.ai واختر طريقة تسجيل الدخول. يؤدي تسجيل الدخول إلى إنشاء حساب Perplexity، ولكن ليس مشروع API. عند زيارتك الأولى، يطالبك معالج الإعداد بإنشاء مشروع أو الانضمام إليه قبل أن تتمكن من إنشاء مفتاح، لأن المفاتيح محددة النطاق للمشاريع.
افتح **الإعدادات** في الشريط الجانبي الأيسر واملأ اسم مؤسستك وعنوانها وتفاصيل الضرائب؛ ستظهر هذه المعلومات في فواتيرك. إذا كان لدى شركتك مشروع بالفعل، فاطلب من مسؤول إضافتك إليه بدلاً من إنشاء مشروع ثانٍ. تحصل المشاريع المنفصلة على أرصدة ومفاتيح ائتمانية منفصلة، وهو أمر مفيد لعزل تطبيق إنتاجي عن تجربة.
الخطوة 2: إضافة طريقة دفع وأرصدة
افتح صفحة الفواتير وأضف بطاقة. وفقًا للوثائق، لا يؤدي إضافة طريقة دفع إلى فرض رسوم على البطاقة؛ بل يخزن التفاصيل للاستخدام المستقبلي. ثم اشترِ الأرصدة. يتوفر الرصيد، وتفاصيل الاستخدام لكل نموذج، وسجل الفواتير كلها في هذه الصفحة.
هناك تفصيلان مهمان هنا. يتم فوترة واجهة برمجة التطبيقات من أرصدة مدفوعة مسبقًا، وإذا نفد الرصيد، فسيتم حظر مفاتيحك حتى تقوم بتعبئة الرصيد. تصف الوثائق هذا الفشل بأنه 401، وليس 402، لذا يبدو التطبيق الذي نفدت أرصدته كخطأ في المصادقة للوهلة الأولى. وبجانب **إعادة التحميل التلقائي**، انقر على **تغيير التفضيلات** لجعل وحدة التحكم تضيف الأرصدة تلقائيًا عندما ينخفض الرصيد عن الحد الذي تحدده. قم بتشغيل ذلك قبل أن ينتقل أي شيء إلى الإنتاج.
لا تنشر الوثائق حدًا أدنى للمبلغ المشتراة، لذا اعتمد على ما تعرضه صفحة الفواتير. تعتمد فئة استخدامك، التي تحدد حدود المعدل الخاص بك، على الأرصدة التراكمية المشتراة على مدار عمر الحساب، وليس على الرصيد الحالي.
الخطوة 3: إنشاء مفتاح API
افتح صفحة مفاتيح API في وحدة التحكم وأنشئ مفتاحًا. امنحه اسمًا وصفيًا مثل dev-laptop أو prod-search-worker. بعد الإنشاء، يكون الاسم هو الطريقة الوحيدة للتمييز بين المفاتيح، لأن القيمة الكاملة تظهر مرة واحدة ولا يمكن استردادها مرة أخرى. انسخها فورًا.
ضع المفتاح في متغير بيئة، وليس في التعليمات البرمجية أبدًا:
export PERPLEXITY_API_KEY="pplx-your-key-here"
على Windows، استخدم setx PERPLEXITY_API_KEY "pplx-your-key-here" وافتح طرفية جديدة.
يمكنك إنشاء عدة مفاتيح ضمن مشروع واحد، لذا أنشئ مفتاحًا واحدًا لكل بيئة ولكل خدمة. إلغاء المفتاح دائم، وهو ما تريده عندما يتسرب مفتاح. إذا لم تكن متأكدًا مما إذا كان المفتاح قد تسرب بالفعل إلى مستودع، فقم بتشغيل ماسح ضوئي للأسرار على سجل git الخاص بك قبل التدوير.
الخطوة 4: إجراء أول طلب Sonar
نقطة النهاية الحالية هي POST https://api.perplexity.ai/v1/agent. المصادقة هي رأس حامل قياسي، Authorization: Bearer $PERPLEXITY_API_KEY. يأخذ الجسم model وسلسلة input. معرف نموذج Sonar على نقطة النهاية هذه هو perplexity/sonar، وتخبر إضافة أداة web_search النموذج بالبحث في الويب المباشر وإرفاق المصادر.
اسأله شيئًا بإجابة حقيقية تتغير بمرور الوقت:
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
تحمل الاستجابة output_text، وهي الإجابة كنص عادي، ومصفوفة output تحتوي على عنصر واحد لكل خطوة قام بها النموذج. يحمل عنصر message الإجابة؛ ويسرد عنصر search_results الصفحات التي قرأها، كل منها مع url و title و snippet و date. يبلغ كائن usage عن عدد الرموز والتكلفة. يعني status من completed أن التشغيل قد انتهى.
نفس الطلب في Python باستخدام SDK الرسمي:
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، فقم بتعيين base_url="https://api.perplexity.ai/v1" واستدعاء client.responses.create() بنفس الوسائط. يقوم SDK بتوجيهها إلى /v1/responses، والتي تقبلها Perplexity كاسم مستعار. تجمع الإعدادات المسبقة (fast, low, medium, high, xhigh) نموذجًا وميزانيات للرموز وأدوات لك؛ وفي OpenAI SDK تمررها عبر extra_body.
إذا كنت تستخدم نموذج إكمال المحادثات القديم
ترسل التعليمات البرمجية القديمة messages إلى https://api.perplexity.ai/v1/sonar بمعرفات النماذج sonar، sonar-pro، sonar-reasoning-pro، أو sonar-deep-research، وتقرأ choices[0].message.content. يعمل هذا النموذج حتى 27 سبتمبر 2026. دليل الترحيل يربط sonar بـ perplexity/sonar، و sonar-pro بـ perplexity/sonar مع الإعداد المسبق low، والبحث العميق بالإعداد المسبق high. تنتقل خيارات search_domain_filter و search_recency_filter إلى داخل أداة web_search ككائن filters.
الخطوة 5: تخزين المفتاح وحفظ الطلب في Apidog
أمر curl يعمل مرة واحدة ليس اختبارًا. إليك الإعداد الذي نستخدمه في Apidog ليبقى المفتاح بعيدًا عن السحابة ويتم تشغيل الطلب عند الطلب.
**أنشئ بيئة.** أضف بيئة تسمى Perplexity بمتغيرين: base_url مضبوطًا على https://api.perplexity.ai كقيمة مشتركة، و PERPLEXITY_API_KEY مع القيمة المشتركة التي تُركت كعنصر نائب والمفتاح الحقيقي في **القيمة المحلية** فقط. تعيش القيم المحلية في ذاكرة التخزين المؤقت لعميلك ولا تتم مزامنتها أبدًا مع أعضاء الفريق، وهذا هو الهدف الأساسي. يتناول دليلنا حول البيئات والمتغيرات السرية في Apidog تقسيم القيم المشتركة مقابل القيم المحلية بمزيد من التفصيل.
**أنشئ الطلب.** طلب جديد، POST {{base_url}}/v1/agent. أضف رأس Authorization: Bearer {{PERPLEXITY_API_KEY}}، اضبط نوع الجسم على JSON، والصق نفس الجسم كما في أمر curl أعلاه. حدد بيئة Perplexity وانقر على إرسال. يجب أن ترى output_text وكتلة search_results في لوحة الاستجابة.
**حوّلها إلى اختبار.** أضف ثلاثة تأكيدات: رمز الحالة هو 200، $.status يساوي completed، و $.output_text ليس فارغًا. احفظ الطلب في سيناريو اختبار. الآن يمكن لأي شخص في الفريق سحب المشروع، ولصق مفتاحه الخاص في القيمة المحلية، والتحقق من إعداداته بنقرة واحدة. تدوير المفتاح يعني تعديل حقل واحد، وليس البحث في النصوص البرمجية.
إذا لم يكن لديك بعد، قم بتنزيل Apidog مجانًا؛ الخطة المجانية تغطي أربعة مستخدمين، وهو ما يكفي لفريق صغير لمشاركة المشروع.
حدود المعدل وتكلفة الطلب
تتغير حدود المعدل على Agent API بناءً على فئة استخدامك، ويتم تحديد الفئات حسب مشتريات الرصيد مدى الحياة، وفقًا لصفحة حدود المعدل:
| الفئة | الأرصدة المشتراة | الطلبات في الثانية | الطلبات في الدقيقة |
|---|---|---|---|
| 0 | 0 دولار | 1 | 50 |
| 1 | 50 دولار فما فوق | 3 | 150 |
| 2 | 250 دولار فما فوق | 8 | 500 |
| 3 | 500 دولار فما فوق | 17 | 1,000 |
| 4 | 1,000 دولار فما فوق | 33 | 4,000 |
| 5 | 5,000 دولار فما فوق | 33 | 8,000 |
تستخدم الحدود خوارزمية السطل المتسرب (leaky-bucket)، لذلك تمر الدفعات القصيرة التي تصل إلى الحد الأقصى. عندما تتجاوز الحد، تُرجع واجهة برمجة التطبيقات رمز 429 مع رأس Retry-After، ولا يتم فوترة الطلبات المرفوضة. تظهر فئتك الحالية في صفحة التسعير بوحدة التحكم تحت علامة تبويب فئات الاستخدام.
فيما يتعلق بالتسعير، تكفي هذه الفقرة هنا. تسرد صفحة التسعير perplexity/sonar على Agent API بسعر 0.25 دولار لكل مليون رمز إدخال و 2.50 دولار لكل مليون رمز إخراج، بالإضافة إلى 0.0025 دولار لكل استدعاء web_search. نماذج Sonar القديمة لإكمال المحادثات تتم محاسبتها بشكل مختلف: sonar بسعر 1 دولار لكل مليون رمز إدخال وإخراج، بالإضافة إلى 5 إلى 12 دولارًا لكل ألف طلب اعتمادًا على حجم سياق البحث. للحصول على تفاصيل كاملة وزاوية حساب Pro، راجع دليل Perplexity API الخاص بنا.
الأخطاء الشائعة وكيفية إصلاحها
**401 غير مصرح به.** ثلاثة أسباب، بترتيب الاحتمالية: الرأس خاطئ (يجب أن يكون Authorization: Bearer <key>، ويجب تصدير متغير shell في نفس الطرفية)، تم إبطال المفتاح، أو رصيد الائتمان صفر. تحقق من صفحة الفواتير قبل إعادة إنشاء أي شيء. يثير Python SDK خطأ AuthenticationError لهذا الغرض.
**400 طلب سيء.** عادةً ما يكون جسم طلب من التنسيق القديم تم إرساله إلى نقطة النهاية الجديدة: messages بدلاً من input، أو معرف نموذج sonar-pro مجرد على /v1/agent. يعرض SDK هذا كخطأ ValidationError.
**404 غير موجود.** المسار خاطئ. /v1/agent هو Agent API و /v1/sonar هو نقطة نهاية إكمال المحادثات القديمة؛ لا تدرج الوثائق أي شيء آخر.
**429 طلبات كثيرة جدًا.** لقد وصلت إلى حد فئتك. اقرأ Retry-After، انتظر هذه المدة، ثم أعد المحاولة بأسلوب التراجع الأسي والتذبذب (exponential backoff and jitter). شراء الأرصدة يرفع فئتك إذا كنت بحاجة إلى إنتاجية مستمرة. يعرض دليل معالجة الأخطاء الخاص بـ SDK نمط RateLimitError.
**500 أو 503.** من جانب الخادم. أعد المحاولة مع تأخير؛ فحلقات إعادة المحاولة الضيقة تجعل تحديد المعدل أسوأ.
الأسئلة الشائعة
هل يوجد مفتاح Perplexity API مجاني؟
لا توجد فئة مجانية موثقة. تعمل واجهة برمجة التطبيقات بنظام الدفع حسب الاستخدام من رصيد ائتماني مدفوع مسبقًا، ويتم حظر المشروع الذي لا يحتوي على أرصدة. تكلفة الطلب الأول باستخدام perplexity/sonar وبحث ويب واحد هي جزء من سنت، لذا فإن تعبئة رصيد صغيرة تغطي الكثير من الاختبارات.
ما هو معرف النموذج الذي يجب أن أستخدمه للطلب الأول؟
استخدم perplexity/sonar على /v1/agent مع أداة web_search. إنه الخيار الأرضي الأقل تكلفة والذي يربط دليل الترحيل معرفات sonar و sonar-pro القديمة به. قم بالتبديل إلى إعداد مسبق مثل low أو medium عندما تريد أن تختار Perplexity النموذج وميزانية البحث لك.
هل أحتاج إلى Agent API إذا كنت أريد نتائج البحث فقط؟
لا. تُرجع Search API المنفصلة نتائج مرتبة دون تشغيل نموذج، وهو أرخص عندما تقوم بتغذية الصفحات في مسار عملك الخاص. يعرض دليلنا التفصيلي حول Perplexity Search API شكل الطلب والمرشحات.
كيف أقوم بتدوير مفتاح دون توقف الخدمة؟
أنشئ مفتاحًا ثانيًا في نفس المشروع، وانشره في كل مكان تم استخدام المفتاح القديم فيه، وتأكد من حركة المرور على المفتاح الجديد، ثم قم بإلغاء المفتاح القديم. الإلغاء دائم، لذا قم بتحديث كل مستهلك أولاً. تكشف Perplexity أيضًا عن نقاط نهاية /generate_auth_token و /revoke_auth_token إذا كنت ترغب في برمجة التدوير.
خاتمة
سجل الدخول، أنشئ مشروعًا، اشترِ أرصدة، أنشئ مفتاحًا، أرسل طلبًا واحدًا إلى /v1/agent باستخدام perplexity/sonar. هذا هو المسار الكامل. قم بتخزين المفتاح كقيمة محلية في Apidog واحفظ الطلب كاختبار، وسيحصل الشخص التالي في فريقك على إعداد قابل للتحقق في دقائق. إذا كان لا يزال لديك تعليمات برمجية على نقطة نهاية إكمال المحادثات، فقم بترحيلها قبل 27 سبتمبر 2026.