OpenAI Compatibility

Overview

Perplexity’s Agent API is fully compatible with OpenAI’s Responses API interface. You can use your existing OpenAI client libraries by simply changing the base URL and providing your Perplexity API key.

Endpoint Note: Perplexity’s canonical Agent API endpoint is POST /v1/agent. For OpenAI SDK compatibility, POST /v1/responses is also accepted as an alias — the OpenAI SDK automatically routes client.responses.create() to /v1/responses, 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 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.4",
    input="Explain the key differences between REST and GraphQL APIs"
)

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: "Explain the key differences between REST and GraphQL APIs"
});

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 follows OpenAI’s Responses API request/response format. The OpenAI SDK’s client.responses.create() method works out of the box — the SDK sends requests to /v1/responses, which Perplexity accepts alongside the canonical /v1/agent endpoint.

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.4",
    input="Explain the key differences between REST and GraphQL APIs"
)

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: "Explain the key differences between REST and GraphQL APIs"
});

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

Using Presets

Presets are pre-configured setups optimized for specific use cases. Use extra_body to pass presets via the OpenAI SDK:

Python
Typescript

from openai import OpenAI

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

# Pass preset via extra_body
response = client.responses.create(
    input="What are the key differences between the latest iPhone and Samsung Galaxy flagship phones?",
    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 type casting (as any) to pass preset via extra_body
const response = await (client.responses.create as any)({
  input: "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones?",
  extra_body: {
    "preset": "pro-search"
  }
});

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.4",
    input="Explain the key differences between REST and GraphQL APIs"
)

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: "Explain the key differences between REST and GraphQL APIs"
});

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.4",
    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 built-in tools, including web search. Use extra_body to pass tools via the OpenAI SDK:

Python
Typescript

from openai import OpenAI

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

# Pass tools via extra_body
response = client.responses.create(
    model="openai/gpt-5.4",
    input="Which companies announced the largest AI acquisitions this quarter?",
    extra_body={
        "tools": [
            {
                "type": "web_search",
                "filters": {
                    "search_domain_filter": ["techcrunch.com", "crunchbase.com"]
                }
            }
        ]
    }
)

print(response.output_text)

import OpenAI from 'openai';

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

// Use type casting (as any) to pass tools via extra_body
const response = await (client.responses.create as any)({
  model: "openai/gpt-5-mini",
  input: "Which companies announced the largest AI acquisitions this quarter?",
  extra_body: {
    "tools": [
      {
        "type": "web_search",
        "filters": {
          "search_domain_filter": ["techcrunch.com", "crunchbase.com"]
        }
      }
    ]
  }
});

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.4)
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.

Endpoint Mapping

Method	Perplexity Endpoint	OpenAI Equivalent	Notes
`client.responses.create()`	`POST /v1/agent`	`POST /v1/responses`	Both paths accepted by Perplexity for compatibility

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

Response Structure

Agent API

Perplexity’s Agent API matches OpenAI’s Responses API response 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.4",
    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.4",
    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 were the biggest tech IPOs this year and how did they perform on day one?",
    extra_body={"preset": "pro-search"}
)

# After (Perplexity SDK) - direct parameter
response = client.responses.create(
    preset="pro-search",
    input="What were the biggest tech IPOs this year and how did they perform on day one?"
)

// Before (OpenAI SDK) - type casting required
const response = await client.responses.create({
  input: "What were the biggest tech IPOs this year and how did they perform on day one?",
  preset: "pro-search"
} as any);

// After (Perplexity SDK) - fully typed
const response = await client.responses.create({
  preset: "pro-search",
  input: "What were the biggest tech IPOs this year and how did they perform on day one?"
});

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

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

Endpoint Mapping

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

Getting Started

Perplexity SDK

Agent API

Search API

Sonar API

Embeddings API

Admin & Management

Resources

​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

​Endpoint Mapping

​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

Endpoint Mapping

Response Structure

Agent API

Best Practices

Recommended: Perplexity SDK

Migrating to the Perplexity SDK

Next Steps