OpenAI Compatibility

Overview

Perplexity’s API is fully compatible with OpenAI’s SDKs. You can use your existing OpenAI client libraries with the Agentic Research 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 Agentic Research API:

Python
TypeScript

from openai import OpenAI

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

response = client.responses.create(
    model="openai/gpt-5-mini",
    input="What are the latest developments in AI?"
)

print(response.output_text)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.perplexity.ai/v2"
});

const response = await client.responses.create({
  model: "openai/gpt-5-mini",
  input: "What are the latest developments in AI?"
});

console.log(response.output_text);

Configuration

Setting Up the OpenAI SDK

Configure OpenAI SDKs to work with Perplexity by setting the base_url to https://api.perplexity.ai/v2:

Python
TypeScript

from openai import OpenAI

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

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: "YOUR_PERPLEXITY_API_KEY",
  baseURL: "https://api.perplexity.ai/v2"
});

Important: Use base_url="https://api.perplexity.ai/v2" (with /v2) for the Agentic Research API.

Perplexity’s Agentic Research API is fully compatible with OpenAI’s Agentic Research API interface.

Basic Usage

Python
TypeScript

from openai import OpenAI

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

response = client.responses.create(
    model="openai/gpt-5-mini",
    input="What are the latest developments in AI?"
)

print(response.output_text)
print(f"Response ID: {response.id}")

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.perplexity.ai/v2"
});

const response = await client.responses.create({
  model: "openai/gpt-5-mini",
  input: "What are the latest developments in AI?"
});

console.log(response.output_text);
console.log(`Response ID: ${response.id}`);

Using Presets

Presets are pre-configured setups optimized for specific use cases. Use the extra_body parameter (Python) or cast the parameter (TypeScript) to pass presets:

Python
TypeScript

from openai import OpenAI

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

# Use a preset instead of specifying model and parameters
response = client.responses.create(
    input="What are the latest developments in AI?",
    extra_body={
        "preset": "pro-search"
    }
)

print(response.output_text)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.perplexity.ai/v2"
});

// Use a preset instead of specifying model and parameters
const response = await client.responses.create({
  input: "What are the latest developments in AI?",
  preset: "pro-search"
} as any);

console.log(response.output_text);

See Agentic Research API Presets for available presets and their configurations.

Using Third-Party Models

You can also specify third-party models directly instead of using presets:

Python
TypeScript

from openai import OpenAI

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

response = client.responses.create(
    model="openai/gpt-5-mini",
    input="What are the latest developments in AI?"
)

print(response.output_text)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.perplexity.ai/v2"
});

const response = await client.responses.create({
  model: "openai/gpt-5-mini",
  input: "What are the latest developments in AI?"
});

console.log(response.output_text);

Streaming Responses

Streaming works with the Agentic Research API:

Python
TypeScript

from openai import OpenAI

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

response = client.responses.create(
    model="openai/gpt-5-mini",
    input="Write a bedtime story about a unicorn.",
    stream=True
)

for event in response:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.perplexity.ai/v2"
});

const response = await client.responses.create({
  model: "openai/gpt-5-mini",
  input: "Write a bedtime story about a unicorn.",
  stream: true
});

for await (const event of response) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

Using Tools

The Agentic Research API supports tools, including web search:

Python
TypeScript

from openai import OpenAI

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

response = client.responses.create(
    model="openai/gpt-5-mini",
    input="What are the latest developments in AI?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": ["techcrunch.com", "wired.com"]
            }
        }
    ],
    instructions="You have access to a web_search tool. Use it for current information."
)

print(response.output_text)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.perplexity.ai/v2"
});

const response = await client.responses.create({
  model: "openai/gpt-5-mini",
  input: "What are the latest developments in AI?",
  tools: [
    {
      type: "web_search",
      filters: {
        search_domain_filter: ["techcrunch.com", "wired.com"]
      }
    }
  ],
  instructions: "You have access to a web_search tool. Use it for current information."
});

console.log(response.output_text);

API Compatibility

Standard OpenAI Parameters

These parameters work exactly the same as OpenAI’s API: Agentic Research API:

model - Model name (use 3rd party models like openai/gpt-5.2)
input - Input text or message array
instructions - System instructions
max_output_tokens - Maximum tokens in response
stream - Enable streaming responses
tools - Array of tools including web_search

Perplexity-Specific Parameters

Agentic Research API:

preset - Preset name (use Perplexity presets like pro-search)
tools[].filters - Search filters within web_search tool
tools[].user_location - User location for localized results

See Agentic Research API Reference for complete parameter details.

Response Structure

Agentic Research API

Perplexity Agentic Research API matches OpenAI’s Agentic Research API format:

output - Structured output array containing messages with content[].text
model - The model name used
usage - Token consumption details
id, created_at, status - Response metadata

Best Practices

Use the correct base URL

Always use https://api.perplexity.ai/v2 (with /v2) for the Agentic Research API.

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

Handle errors gracefully

Use the OpenAI SDK’s error handling:

from openai import OpenAI, APIError, RateLimitError

try:
    response = client.responses.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:

response = client.responses.create(
    model="openai/gpt-5-mini",
    input="Long query...",
    stream=True
)

for event in response:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Recommended: Perplexity SDK

We recommend using Perplexity’s native SDKs for the best developer experience:

Cleaner preset syntax - Use preset="pro-search" directly instead of extra_body={"preset": "pro-search"}
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

Responses Quickstart

Get started with Agentic Research API using OpenAI SDKs.

Prompt Guide

Learn best practices for prompting the Agentic Research API.

API Reference

View complete API documentation for the Agentic Research endpoint.

Migrating to the Perplexity SDK

Switch to the Perplexity SDK for enhanced features and cleaner syntax. With the Perplexity SDK, you can use presets directly without extra_body and get full type safety:

Install the Perplexity SDK

Python
TypeScript

pip install perplexityai

npm install @perplexity-ai/perplexity_ai

Update the import and client

Python
TypeScript

# Before (OpenAI SDK)
from openai import OpenAI
client = OpenAI(
    api_key="pplx-...",
    base_url="https://api.perplexity.ai/v2"
)

# After (Perplexity SDK)
from perplexity import Perplexity
client = Perplexity(api_key="pplx-...")
# Or just: client = Perplexity() if PERPLEXITY_API_KEY env var is set

// Before (OpenAI SDK)
import OpenAI from 'openai';
const client = new OpenAI({
  apiKey: "pplx-...",
  baseURL: "https://api.perplexity.ai/v2"
});

// After (Perplexity SDK)
import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity({ apiKey: "pplx-..." });
// Or just: const client = new Perplexity() if PERPLEXITY_API_KEY env var is set

No base URL needed - The Perplexity SDK automatically uses the correct endpoint.

Update the API calls

The API calls are very similar:

Python
TypeScript

# Agentic Research API - same interface
response = client.responses.create(
    model="openai/gpt-5-mini",
    input="Hello!"
)

// Agentic Research API - same interface
const response = await client.responses.create({
  model: "openai/gpt-5-mini",
  input: "Hello!"
});

Use presets with cleaner syntax

The Perplexity SDK supports presets with cleaner syntax compared to OpenAI SDK:

Python
TypeScript

# Before (OpenAI SDK) - extra_body required
response = client.responses.create(
    input="What are the latest developments in AI?",
    extra_body={"preset": "pro-search"}
)

# After (Perplexity SDK) - direct parameter
response = client.responses.create(
    preset="pro-search",
    input="What are the latest developments in AI?"
)

// Before (OpenAI SDK) - type casting required
const response = await client.responses.create({
  input: "What are the latest developments in AI?",
  preset: "pro-search"
} as any);

// After (Perplexity SDK) - fully typed
const response = await client.responses.create({
  preset: "pro-search",
  input: "What are the latest developments in AI?"
});

Getting Started

Perplexity SDK

Agentic Research API

Search API

Sonar API

Admin & Management

Resources

OpenAI Compatibility

Overview

Quick Start

Configuration

Setting Up the OpenAI SDK

Basic Usage

Using Presets

Using Third-Party Models

Streaming Responses

Using Tools

API Compatibility

Standard OpenAI Parameters

Perplexity-Specific Parameters

Response Structure

Agentic Research API

Best Practices

Recommended: Perplexity SDK

Next Steps

Responses Quickstart

Prompt Guide

API Reference

Migrating to the Perplexity SDK

Getting Started

Perplexity SDK

Agentic Research API

Search API

Sonar API

Admin & Management

Resources

​Overview

​Quick Start

​Configuration

​Setting Up the OpenAI SDK

​Basic Usage

​Using Presets

​Using Third-Party Models

​Streaming Responses

​Using Tools

​API Compatibility

​Standard OpenAI Parameters

​Perplexity-Specific Parameters

​Response Structure

​Agentic Research API

​Best Practices

​Recommended: Perplexity SDK

​Next Steps

Responses Quickstart

Prompt Guide

API Reference

​Migrating to the Perplexity SDK

Overview

Quick Start

Configuration

Setting Up the OpenAI SDK

Basic Usage

Using Presets

Using Third-Party Models

Streaming Responses

Using Tools

API Compatibility

Standard OpenAI Parameters

Perplexity-Specific Parameters

Response Structure

Agentic Research API

Best Practices

Recommended: Perplexity SDK

Next Steps

Migrating to the Perplexity SDK