Perplexity Gateway API

Overview

The Gateway API provides unified access to frontier models from Anthropic, OpenAI, Google, xAI, and Perplexity through a single endpoint and a single API key. Send requests in the OpenAI Chat Completions or Anthropic Messages format, pick any model from the catalog, and the platform routes each request to a healthy deployment automatically — no per-provider accounts, SDKs, or failover logic on your side. Any model in the catalog can be called through either schema, regardless of the model’s original provider: you can call GPT models through the Anthropic Messages format and Claude models through OpenAI Chat Completions. This makes the Gateway a drop-in replacement for existing OpenAI or Anthropic integrations — only the base URL and API key need to change. Use the Gateway API for direct model access with your own prompts and tools. For web-grounded answers with built-in citations, use the Agent API. The base URL is https://api.perplexity.ai/router/v1, and your existing Perplexity API key works as-is.

Installation

The Gateway API supports both the OpenAI Chat Completions and the Anthropic Messages formats, so you can use either provider’s official SDK — install whichever matches your integration (or both):

pip install openai       # OpenAI Chat Completions format
pip install anthropic    # Anthropic Messages format

npm install openai              # OpenAI Chat Completions format
npm install @anthropic-ai/sdk   # Anthropic Messages format

Authentication

Set your API key as an environment variable:

macOS/Linux
Windows

export PERPLEXITY_API_KEY="your_api_key_here"

setx PERPLEXITY_API_KEY "your_api_key_here"

Requests authenticate with an Authorization: Bearer header, which the SDKs set for you from the api_key parameter.

Basic Usage

Point the OpenAI SDK at the Gateway base URL and pass any model id from the catalog. Model ids use creator/model-name slugs, so switching providers is a one-line change:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai/router/v1"
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain the CAP theorem in two sentences."}
    ]
)

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

import OpenAI from 'openai';

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

const response = await client.chat.completions.create({
    model: "anthropic/claude-sonnet-5",
    max_tokens: 1024,
    messages: [
        { role: "user", content: "Explain the CAP theorem in two sentences." }
    ]
});

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

curl -X POST 'https://api.perplexity.ai/router/v1/chat/completions' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain the CAP theorem in two sentences."}
    ]
  }' | jq

Response

{
  "id": "chatcmpl-Xr7aQ2mVb9L4tW8pDcEfGh1JkNs0y",
  "object": "chat.completion",
  "created": 1753747200,
  "model": "anthropic/claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The CAP theorem states that a distributed system can guarantee at most two of three properties: consistency, availability, and partition tolerance. Since network partitions are unavoidable in practice, designers must choose between consistency and availability when a partition occurs.",
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 52,
    "total_tokens": 70,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

The response echoes the model id you requested, and you are always billed at that model’s published rates no matter how the request was served.

Streaming

Set stream: true to receive tokens as server-sent events. To get token usage with a streamed response, also set stream_options: {"include_usage": true} — usage then arrives in a final chunk before data: [DONE]:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai/router/v1"
)

stream = client.chat.completions.create(
    model="openai/gpt-5.6-terra",
    messages=[
        {"role": "user", "content": "Write a haiku about network latency."}
    ],
    stream=True,
    stream_options={"include_usage": True}
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print(f"\n\nTokens used: {chunk.usage.total_tokens}")

import OpenAI from 'openai';

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

const stream = await client.chat.completions.create({
    model: "openai/gpt-5.6-terra",
    messages: [
        { role: "user", content: "Write a haiku about network latency." }
    ],
    stream: true,
    stream_options: { include_usage: true }
});

for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
        process.stdout.write(chunk.choices[0].delta.content);
    }
    if (chunk.usage) {
        console.log(`\n\nTokens used: ${chunk.usage.total_tokens}`);
    }
}

curl -N -X POST 'https://api.perplexity.ai/router/v1/chat/completions' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-terra",
    "messages": [
      {"role": "user", "content": "Write a haiku about network latency."}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Anthropic Messages

The same models are available in the Anthropic Messages format at /router/v1/messages, so code written against the Anthropic SDK works with a base-URL change:

The Anthropic SDK appends /v1/messages to its base URL, so configure it with https://api.perplexity.ai/router (no /v1). The OpenAI SDK appends /chat/completions and is configured with https://api.perplexity.ai/router/v1.

from anthropic import Anthropic
import os

client = Anthropic(
    api_key=os.environ.get("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai/router"
)

message = client.messages.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain the CAP theorem in two sentences."}
    ]
)

print(message.content[0].text)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
    apiKey: process.env.PERPLEXITY_API_KEY,
    baseURL: "https://api.perplexity.ai/router"
});

const message = await client.messages.create({
    model: "anthropic/claude-sonnet-5",
    max_tokens: 1024,
    messages: [
        { role: "user", content: "Explain the CAP theorem in two sentences." }
    ]
});

console.log(message.content[0].text);

curl -X POST 'https://api.perplexity.ai/router/v1/messages' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain the CAP theorem in two sentences."}
    ]
  }' | jq

Discovering Models

List the current catalog at any time — the response is OpenAI-compatible, sorted by model id, and includes each model’s base token prices in USD per 1M tokens:

curl 'https://api.perplexity.ai/router/v1/models' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" | jq

Response

{
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-opus-5",
      "object": "model",
      "created": 0,
      "owned_by": "anthropic",
      "pricing": {
        "input": 5,
        "output": 25,
        "cache_write": 6.25,
        "cache_read": 0.5,
        "unit": "usd_per_1m_tokens"
      }
    },
    {
      "id": "anthropic/claude-sonnet-5",
      "object": "model",
      "created": 0,
      "owned_by": "anthropic",
      "pricing": {
        "input": 2,
        "output": 10,
        "cache_write": 2.5,
        "cache_read": 0.2,
        "unit": "usd_per_1m_tokens"
      }
    }
  ]
}

See the models page for the full catalog with pricing.

Next Steps

Models & Pricing

The model catalog with per-token rates.

Routing & Reliability

How requests are routed and what happens when a provider fails.

Chat Completions Reference

Full request and response schema.

Messages Reference

The Anthropic-compatible endpoint schema.

Need help? Check out our community for support.

Getting Started

Gateway API

Agent API

Search API

Embeddings API

Perplexity SDK

Admin & Management

Resources

Legacy API

Perplexity Gateway API

Overview

Installation

Authentication

Basic Usage

Streaming

Anthropic Messages

Discovering Models

Next Steps

Models & Pricing

Routing & Reliability

Chat Completions Reference

Messages Reference

​Overview

​Installation

​Authentication

​Basic Usage

​Streaming

​Anthropic Messages

​Discovering Models

​Next Steps

Models & Pricing

Routing & Reliability

Chat Completions Reference

Messages Reference

Overview

Installation

Authentication

Basic Usage

Streaming

Anthropic Messages

Discovering Models

Next Steps