How to Use Perplexity API With Python OpenAI SDK

You want to call the Perplexity API from Python code but prefer using the familiar OpenAI SDK instead of a separate library. The Perplexity API is fully compatible with the OpenAI client because it uses the same chat completions endpoint format. This article explains how to configure the OpenAI Python SDK to connect to Perplexity, send queries, and handle responses. You will learn the required endpoint URL, authentication method, and model parameters to switch between OpenAI and Perplexity with minimal code changes.

What Is the Perplexity API and Why Use the OpenAI SDK

The Perplexity API provides access to large language models hosted by Perplexity, including Sonar models optimized for real-time search and reasoning. The API is designed as a drop-in replacement for the OpenAI chat completions endpoint. This means you can use the same Python code that calls GPT-4 to call Perplexity models by changing only the endpoint URL and API key.

Using the OpenAI SDK has several advantages. You avoid installing a separate Perplexity library. You reuse existing code, authentication patterns, and error handling you already have for OpenAI. The SDK handles streaming, token counting, and retries uniformly. Perplexity supports the same request and response structure as OpenAI, so messages, roles, and parameters like temperature and max_tokens work identically.

Before you start, you need a Perplexity API key. Sign in to your Perplexity account, go to the API keys section in your account settings, and create a new key. Copy the key and keep it secure. You also need Python 3.8 or newer and the openai package installed. Install it with pip install openai if you have not already.

Steps to Configure the OpenAI SDK for Perplexity API

The configuration requires two changes to the OpenAI client initialization: the base_url and the api_key. Everything else follows the standard OpenAI chat completion pattern.

1. Install or update the openai package
   Run pip install –upgrade openai in your terminal to ensure you have version 1.0 or later. Versions before 1.0 use a different client API that is incompatible with this guide.
2. Import the OpenAI class
   Add from openai import OpenAI at the top of your Python script. This imports the modern client class.
3. Create the client with Perplexity endpoint
   Initialize the client like this: client = OpenAI(api_key=’your-perplexity-api-key’, base_url=’https://api.perplexity.ai’). Replace the api_key string with your actual key. The base_url must point to the Perplexity API root.
4. Send a chat completion request
   Call client.chat.completions.create with the model parameter set to a Perplexity model name such as sonar-pro. Pass the messages list as you would for OpenAI. For example: response = client.chat.completions.create(model=’sonar-pro’, messages=[{‘role’: ‘user’, ‘content’: ‘Explain quantum computing in one sentence’}]).
5. Extract the reply
   Read the response content using response.choices[0].message.content. Print or return this string to see the model output.

The complete minimal script looks like this:

from openai import OpenAI

client = OpenAI(
    api_key="pplx-your-key-here",
    base_url="https://api.perplexity.ai"
)

response = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {"role": "user", "content": "What is the capital of France?"}
    ]
)

print(response.choices[0].message.content)

Replace pplx-your-key-here with your actual Perplexity API key. The model sonar-pro is Perplexity flagship model. Other available models include sonar-small-chat, sonar-medium-chat, and sonar-small-online. Check the Perplexity API documentation for the latest list.

Streaming Responses

To stream the response token by token, add stream=True to the create call. Then iterate over the response object:

stream = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

Streaming works identically to the OpenAI streaming API. Each chunk contains a delta object with the incremental content.

Passing System Messages

Perplexity supports system messages to set the behavior of the assistant. Add a system message at the beginning of the messages array:

messages = [
    {"role": "system", "content": "You are a helpful assistant that answers in rhymes."},
    {"role": "user", "content": "What is the speed of light?"}
]

The model will follow the system instruction. This is useful for setting tone, format, or domain-specific rules.

Common Mistakes and Things to Avoid

Using the Wrong Base URL

The base URL must be exactly https://api.perplexity.ai without a trailing path like /v1. The OpenAI SDK appends /chat/completions automatically. If you set base_url to https://api.perplexity.ai/v1, the SDK will send requests to https://api.perplexity.ai/v1/chat/completions, which is incorrect. Always use the root URL.

Passing an OpenAI API Key

The api_key parameter must be a Perplexity API key, not an OpenAI key. Perplexity keys start with pplx-. If you use an OpenAI key, the Perplexity server returns a 401 authentication error. Double-check the key prefix and regenerate it from your Perplexity dashboard if needed.

Using Deprecated OpenAI Client Versions

The openai package version 0.x uses a different client class named openai.ChatCompletion. That class does not accept base_url or api_key as initialization parameters. Upgrade to version 1.0 or later with pip install –upgrade openai. The modern client class is OpenAI.

Model Name Typos

Perplexity model names are case-sensitive and must match exactly. Common typos include using underscores instead of hyphens, or misspelling sonar. Check the exact model name in the Perplexity API documentation. An invalid model name returns a 404 error with message Model not found.

Ignoring Rate Limits

Perplexity enforces rate limits based on your subscription plan. Free tier accounts have lower limits. If you receive a 429 Too Many Requests error, implement exponential backoff in your code. The OpenAI SDK does not handle Perplexity rate limits automatically.

Item	OpenAI SDK + Perplexity	Perplexity Native SDK
Installation	pip install openai	pip install perplexity-ai
Client initialization	OpenAI(api_key, base_url)	Perplexity(api_key)
Request format	Standard OpenAI chat completions	Perplexity-specific methods
Streaming support	Yes, same as OpenAI	Yes, different syntax
Model selection	model parameter as string	model parameter as string
Error handling	OpenAI exception classes	Perplexity exception classes
Code reuse with OpenAI	Full reuse, change only base_url and api_key	No reuse, rewrite all calls

Using the OpenAI SDK with Perplexity gives you the advantage of code portability. You can switch between providers by changing two lines. The Perplexity native SDK offers additional features like built-in search integration, but the OpenAI SDK covers the core chat functionality completely.

You can now call the Perplexity API from Python using the OpenAI SDK with minimal setup. Start by copying the initialization code from this article and replacing the API key and model name. Test with a simple query before building more complex applications. For production use, store the API key in an environment variable instead of hardcoding it in your script. Use os.environ.get(‘PERPLEXITY_API_KEY’) to read the key securely and keep it out of version control.