​
Overview

Perplexity’s Sonar API is fully compatible with OpenAI’s Chat Completions API format. This means you can use existing OpenAI client libraries and simply change the base URL to start using Perplexity’s web search-powered models.

​
API Compatibility

​
Standard OpenAI Parameters

These parameters work exactly the same as OpenAI’s API:
  • model - Model name (use Perplexity model names)
  • messages - Chat messages array
  • temperature - Sampling temperature (0-2)
  • max_tokens - Maximum tokens in response
  • top_p - Nucleus sampling parameter
  • frequency_penalty - Frequency penalty (-2.0 to 2.0)
  • presence_penalty - Presence penalty (-2.0 to 2.0)
  • stream - Enable streaming responses

​
Perplexity-Specific Parameters

These Perplexity-specific parameters are also included:
  • search_domain_filter - Limit or exclude specific domains
  • search_recency_filter - Filter by content recency
  • return_images - Include image URLs in response
  • return_related_questions - Include related questions
  • search_mode - “web” (default) or “academic” mode selector.
See API Reference for more details.

​
Examples with OpenAI SDK

Install the OpenAI library: pip install openai
from openai import OpenAI

client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.perplexity.ai"
)

response = client.chat.completions.create(
model="sonar-pro",
messages=[
  {"role": "system", "content": "Be precise and concise."},
  {"role": "user", "content": "How many stars are there in our galaxy?"}
],
temperature=0.2,
top_p=0.9,
max_tokens=1000,
presence_penalty=0,
frequency_penalty=0,
stream=False,
extra_body={
  "search_mode": "web",
  "search_domain_filter": ["government.gov", "nature.com", "science.org"],
  "search_recency_filter": "month"
}
)

print(response.choices[0].message.content)
print(f"Search Results: {response.search_results}")

​
Understanding the Response Structure

After making a request, your response object will include both standard OpenAI fields and Perplexity-specific fields:
  • choices[0].message.content: The main model response
  • model: The model used
  • usage: Token usage details
  • search_results: (Perplexity) Array of search result objects with titles, URLs, and dates
# Accessing response fields
print(response.choices[0].message.content)  # Main answer
print(response.model)                       # Model name
print(response.usage)                       # Token usage
print(response.search_results)              # Perplexity search results

​
Technical Notes

  • Error format: Same as OpenAI’s API for compatibility
  • Rate limiting: Apply standard rate limiting practices
  • Model names: Use Perplexity model names (sonar-pro, sonar-reasoning, etc.)
  • Authentication: Use Bearer token format in Authorization header