​
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_citations - Include citation URLs in response
  • 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?"}
    ],
    search_mode="web", # tweak these parameters to control the search results
    temperature=0.2,
    top_p=0.9,
    max_tokens=1000,
    presence_penalty=0,
    frequency_penalty=0,
    stream=False,
    search_domain_filter=["government.gov", "nature.com", "science.org"],
    search_recency_filter="month",
    return_citations=True
)

print(response.choices[0].message.content)
print(f"Citations: {response.citations}")

​
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
  • citations: (Perplexity) List of source URLs
  • search_results: (Perplexity) Array of search result objects
# Accessing response fields
print(response.choices[0].message.content)  # Main answer
print(response.model)                       # Model name
print(response.usage)                       # Token usage
print(response.citations)                   # Perplexity citations
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