OpenAI Compatibility

Overview

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

Python
Typescript

from openai import OpenAI

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

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/v1"
});

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/v1:

Python
Typescript

from openai import OpenAI

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

import OpenAI from 'openai';

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

Important: Use base_url="https://api.perplexity.ai/v1" (with /v1) for the Agent API.

Agent API

Perplexity’s Agent API is fully compatible with OpenAI’s Agent API interface.

Basic Usage

Python
Typescript

from openai import OpenAI

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

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/v1"
});

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/v1"
)

# 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/v1"
});

// 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 Agent 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/v1"
)

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/v1"
});

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 Agent API:

Python
Typescript

from openai import OpenAI

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

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/v1"
});

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 Agent 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/v1"
)

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/v1"
});

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: Agent 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

Agent 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 Agent API Reference for complete parameter details.

Response Structure

Agent API

Perplexity Agent API matches OpenAI’s Agent 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/v1 (with /v1) for the Agent API.

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.perplexity.ai/v1"  # 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.

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/v1"
)

# 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/v1"
});

// 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

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

// Agent 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?"
});

Next Steps

Agent API Quickstart

Get started with Agent API using OpenAI SDKs.

Models

Explore direct model selection and third-party models.

API Reference

View complete endpoint documentation.

Output Control

Configure streaming responses and structured outputs with JSON schema.

Model Fallback

Specify multiple models for automatic failover and higher availability.

Filters

Apply filters to web search results.

Getting Started

Perplexity SDK

Agent API

Search API

Sonar API

Browser API

Embeddings API

Admin & Management

Resources

OpenAI Compatibility

Overview

Quick Start

Configuration

Setting Up the OpenAI SDK

Agent API

Basic Usage

Using Presets

Using Third-Party Models

Streaming Responses

Using Tools

API Compatibility

Standard OpenAI Parameters

Perplexity-Specific Parameters

Response Structure

Agent API

Best Practices

Recommended: Perplexity SDK

Migrating to the Perplexity SDK

Next Steps

Agent API Quickstart

Models

API Reference

Output Control

Model Fallback

Filters

​Overview

​Quick Start

​Configuration

​Setting Up the OpenAI SDK

​Agent API

​Basic Usage

​Using Presets

​Using Third-Party Models

​Streaming Responses

​Using Tools

​API Compatibility

​Standard OpenAI Parameters

​Perplexity-Specific Parameters

​Response Structure

​Agent API

​Best Practices

​Recommended: Perplexity SDK

​Migrating to the Perplexity SDK

​Next Steps

Agent API Quickstart

Models

API Reference

Output Control

Model Fallback

Filters

Overview

Quick Start

Configuration

Setting Up the OpenAI SDK

Agent API

Basic Usage

Using Presets

Using Third-Party Models

Streaming Responses

Using Tools

API Compatibility

Standard OpenAI Parameters

Perplexity-Specific Parameters

Response Structure

Agent API

Best Practices

Recommended: Perplexity SDK

Migrating to the Perplexity SDK

Next Steps