OpenAI SDK Compatibility

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.

Endpoint Note: Perplexity’s canonical Sonar API endpoint is POST /v1/sonar. For OpenAI SDK compatibility, POST /chat/completions is also accepted as an alias — the OpenAI SDK automatically routes client.chat.completions.create() to /chat/completions, which Perplexity handles seamlessly. No SDK changes are needed beyond setting the base URL.

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:

Python
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": "What breakthroughs in fusion energy have been announced this year?"}
    ]
)

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 breakthroughs in fusion energy have been announced this year?" }
  ]
});

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:

Python
TypeScript

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.

Python
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": "What breakthroughs in fusion energy have been announced this year?"}
    ]
)

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 breakthroughs in fusion energy have been announced this year?" }
  ]
});

console.log(completion.choices[0].message.content);

Streaming

Streaming works exactly like OpenAI’s API:

Python
TypeScript

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 breakthroughs in fusion energy have been announced this year?"}
    ],
    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 breakthroughs in fusion energy have been announced this year?" }
  ],
  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):

Python
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 array
max_tokens - Maximum tokens in response
stream - Enable streaming responses
temperature - Response randomness (0-2)
top_p - Nucleus sampling parameter
response_format - Response format specification

Perplexity-Specific Parameters

Sonar API supports additional search and response parameters:

search_domain_filter - Limit or exclude specific domains
search_recency_filter - Filter by content recency (“day”, “week”, “month”, “year”)
return_images - Include image URLs in response
return_related_questions - Include related questions
search_mode - “web” (default) or “academic” mode selector
enable_search_classifier - Let AI decide when to search
disable_search - Turn off web search completely

See Sonar API Reference for complete parameter details.

Endpoint Mapping

Method	Perplexity Endpoint	OpenAI Equivalent	Notes
`client.chat.completions.create()`	`POST /v1/sonar`	`POST /chat/completions`	Both paths accepted by Perplexity for compatibility
`client.async_.chat.completions.create()`	`POST /v1/async/sonar`	`POST /async/chat/completions`	Both paths accepted by Perplexity for compatibility

When using the OpenAI SDK, client.chat.completions.create() sends requests to /chat/completions. Perplexity accepts this path as an alias for /v1/sonar, so no SDK configuration changes are needed beyond base_url.

Response Structure

Perplexity responses match OpenAI’s format exactly, with additional fields:

Standard OpenAI Fields

choices[0].message.content - The AI-generated response
model - The model name used
usage - Token consumption details
id, created, object - Standard response metadata

Perplexity-Specific Fields

search_results - Array of web sources with title, url, and date
citations - 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

Sonar Quickstart

Get started with Sonar API using OpenAI SDKs.

Sonar API Features

Learn best practices for prompting and using the Sonar API.

API Reference

View complete API documentation for the Sonar endpoint.

Search Filters

Learn how to control search behavior with filters and parameters.

Getting Started

Perplexity SDK

Agent API

Search API

Sonar API

Embeddings API

Admin & Management

Resources

OpenAI SDK Compatibility

Overview

Quick Start

Configuration

Setting Up the OpenAI SDK

Basic Usage

Streaming

Perplexity-Specific Parameters

API Compatibility

Standard OpenAI Parameters

Perplexity-Specific Parameters

Endpoint Mapping

Response Structure

Standard OpenAI Fields

Perplexity-Specific Fields

Best Practices

Recommended: Perplexity SDK

Next Steps

Sonar Quickstart

Sonar API Features

API Reference

Search Filters

Getting Started

Perplexity SDK

Agent API

Search API

Sonar API

Embeddings API

Admin & Management

Resources

​Overview

​Quick Start

​Configuration

​Setting Up the OpenAI SDK

​Basic Usage

​Streaming

​Perplexity-Specific Parameters

​API Compatibility

​Standard OpenAI Parameters

​Perplexity-Specific Parameters

​Endpoint Mapping

​Response Structure

​Standard OpenAI Fields

​Perplexity-Specific Fields

​Best Practices

​Recommended: Perplexity SDK

​Next Steps

Sonar Quickstart

Sonar API Features

API Reference

Search Filters

Overview

Quick Start

Configuration

Setting Up the OpenAI SDK

Basic Usage

Streaming

Perplexity-Specific Parameters

API Compatibility

Standard OpenAI Parameters

Perplexity-Specific Parameters

Endpoint Mapping

Response Structure

Standard OpenAI Fields

Perplexity-Specific Fields

Best Practices

Recommended: Perplexity SDK

Next Steps