Perplexity AI Python SDK

Warnings

• breaking All llama-3.1-sonar-* and llama-3-sonar-* model names removed Feb 22, 2025. Using them returns a 404/model-not-found error.
  Fix: Use current Sonar family: sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research
• breaking pplx-7b-online, pplx-70b-online, pplx-7b-chat, pplx-70b-chat all deprecated and removed. These were the original Perplexity model names.
  Fix: Migrate to sonar (lightweight) or sonar-pro (advanced)
• breaking R1-1776 removed Aug 1, 2025.
  Fix: Use sonar-reasoning-pro (powered by DeepSeek-R1 with stronger performance)
• deprecated After April 18, 2025: citation tokens and search result counts no longer returned in usage field for Sonar Pro and Sonar Reasoning Pro.
  Fix: Do not rely on usage.citations or usage.search_results_count — these fields removed from API response
• gotcha pip install package is perplexityai but the module you import from is perplexity. These are different names — a common confusion source.
  Fix: pip install perplexityai, then from perplexity import Perplexity
• gotcha Env var is PERPLEXITY_API_KEY. Some third-party docs incorrectly show PPLX_API_KEY (legacy curl examples) or PERPLEXITYAI_API_KEY. Only PERPLEXITY_API_KEY is auto-read by the SDK.
  Fix: export PERPLEXITY_API_KEY=your_key
• gotcha sonar-deep-research is async by design — responses can take minutes. Do not use with short timeouts. Supports reasoning_effort: low/medium/high parameter.
  Fix: Set httpx timeout to 300+ seconds for deep research. Use stream=True to get incremental output.

Install

• pip install perplexityai Official SDK (perplexityai)
• pip install openai OpenAI-compatible alternative

Imports

• Perplexity

  from perplexity import Perplexity

  Package installs as perplexityai but module name is perplexity
• AsyncPerplexity

  from perplexity import AsyncPerplexity

  Same pattern — import from perplexity, not perplexityai

Quickstart

Web-grounded chat completion with citations

from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY automatically

response = client.chat.completions.create(
    model='sonar',
    messages=[{'role': 'user', 'content': 'What happened in AI this week?'}]
)
print(response.choices[0].message.content)