Overview
Perplexity’s Sonar API is fully compatible with OpenAI’s Chat Completions format. You can use your existing OpenAI client libraries with the Sonar API by simply changing the base URL and providing your Perplexity API key.
We recommend using the Perplexity SDK for the best experience with full type safety, enhanced features, and preset support. Use OpenAI SDKs if you’re already integrated and need drop-in compatibility. Quick Start
Use the OpenAI SDK with Perplexity’s Sonar API:
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.perplexity.ai"
)
completion = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "user", "content": "What are the latest developments in AI?"}
]
)
print(completion.choices[0].message.content)
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.perplexity.ai"
});
const completion = await client.chat.completions.create({
model: "sonar-pro",
messages: [
{ role: "user", content: "What are the latest developments in AI?" }
]
});
console.log(completion.choices[0].message.content);
Configuration
Setting Up the OpenAI SDK
Configure OpenAI SDKs to work with Perplexity by setting the base_url to https://api.perplexity.ai:
from openai import OpenAI
client = OpenAI(
api_key="YOUR_PERPLEXITY_API_KEY",
base_url="https://api.perplexity.ai"
)
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: "YOUR_PERPLEXITY_API_KEY",
baseURL: "https://api.perplexity.ai"
});
Important: Use base_url="https://api.perplexity.ai" for the Sonar API.
Basic Usage
Perplexity’s Sonar API is fully compatible with OpenAI’s Chat Completions interface.
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.perplexity.ai"
)
completion = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "user", "content": "What are the latest developments in AI?"}
]
)
print(completion.choices[0].message.content)
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.perplexity.ai"
});
const completion = await client.chat.completions.create({
model: "sonar-pro",
messages: [
{ role: "user", content: "What are the latest developments in AI?" }
]
});
console.log(completion.choices[0].message.content);
Streaming
Streaming works exactly like OpenAI’s API:
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.perplexity.ai"
)
stream = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "user", "content": "What are the latest developments in AI?"}
],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.perplexity.ai"
});
const stream = await client.chat.completions.create({
model: "sonar-pro",
messages: [
{ role: "user", content: "What are the latest developments in AI?" }
],
stream: true
});
for await (const chunk of stream) {
if (chunk.choices[0]?.delta?.content) {
process.stdout.write(chunk.choices[0].delta.content);
}
}
Perplexity-Specific Parameters
Add Perplexity-specific search parameters using extra_body (Python) or direct parameters (TypeScript):
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.perplexity.ai"
)
completion = client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "user", "content": "Latest climate research findings"}
],
extra_body={
"search_domain_filter": ["nature.com", "science.org"],
"search_recency_filter": "month"
}
)
print(completion.choices[0].message.content)
print(f"Sources: {len(completion.search_results)} articles found")
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.perplexity.ai"
});
const completion = await client.chat.completions.create({
model: "sonar-pro",
messages: [
{ role: "user", content: "Latest climate research findings" }
],
search_domain_filter: ["nature.com", "science.org"],
search_recency_filter: "month"
} as any);
console.log(completion.choices[0].message.content);
console.log(`Sources: ${completion.search_results.length} articles found`);
API Compatibility
Standard OpenAI Parameters
These parameters work exactly the same as OpenAI’s API:
model - Model name (use Perplexity model names like sonar-pro)messages - Chat messages arraymax_tokens - Maximum tokens in responsestream - Enable streaming responsestemperature - Response randomness (0-2)top_p - Nucleus sampling parameterresponse_format - Response format specification
Perplexity-Specific Parameters
Sonar API supports additional search and response parameters:
search_domain_filter - Limit or exclude specific domainssearch_recency_filter - Filter by content recency (“day”, “week”, “month”, “year”)return_images - Include image URLs in responsereturn_related_questions - Include related questionssearch_mode - “web” (default) or “academic” mode selectorenable_search_classifier - Let AI decide when to searchdisable_search - Turn off web search completely
Response Structure
Perplexity responses match OpenAI’s format exactly, with additional fields:
Standard OpenAI Fields
choices[0].message.content - The AI-generated responsemodel - The model name usedusage - Token consumption detailsid, created, object - Standard response metadata
Perplexity-Specific Fields
search_results - Array of web sources with title, url, and datecitations - Array of citation URLs referenced in the response
Example Response:
{
"id": "pplx-1234567890",
"model": "sonar-pro",
"created": 1234567890,
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The latest developments in AI include..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 315,
"total_tokens": 327
},
"search_results": [
{
"title": "Latest AI Developments",
"url": "https://example.com/ai-news",
"date": "2025-02-01"
}
],
"citations": [
"https://example.com/ai-news"
]
}
Best Practices
Use the correct base URL
Always use https://api.perplexity.ai for the Sonar API.client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.perplexity.ai" # Correct
)
Handle errors gracefully
Use the OpenAI SDK’s error handling:from openai import OpenAI, APIError, RateLimitError
try:
completion = client.chat.completions.create(...)
except RateLimitError:
print("Rate limit exceeded, please retry later")
except APIError as e:
print(f"API error: {e.message}")
Use streaming for better UX
Stream responses for real-time user experience:stream = client.chat.completions.create(
model="sonar-pro",
messages=[{"role": "user", "content": "Long query..."}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Access search results
Use the search_results field to get accurate source URLs:completion = client.chat.completions.create(
model="sonar-pro",
messages=[{"role": "user", "content": "Latest AI news"}]
)
# Access search results
for result in completion.search_results:
print(f"{result['title']}: {result['url']}")
Recommended: Perplexity SDK
We recommend using Perplexity’s native SDKs for the best developer experience:
- Type safety - Full TypeScript/Python type definitions for all parameters
- Enhanced features - Direct access to all Perplexity-specific features
- Better error messages - Perplexity-specific error handling
- Simpler setup - No need to configure base URLs
See the Perplexity SDK Guide for details.
Next Steps
