Skip to main content

Overview

The Orchestrator API serves Anthropic, OpenAI, Google, xAI, and open-weight models through one Perplexity API key and one credit balance. Send requests in the OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages format and name any model from the catalog by its full ID, such as openai/gpt-6-luna or perplexity/glm-5.3. The platform picks a healthy deployment of that model and retries on another if one fails. To move an existing OpenAI or Anthropic integration, change the base URL, the API key, and the model ID. The Anthropic SDK appends /v1/messages to its base URL, so its base URL has no /v1. Every model supports all three formats; individual features depend on the model. The API is stateless: send the full conversation on every request. Fields that depend on server-side state, such as previous_response_id, return HTTP 400; the FAQ lists them. Which models you can call depends on your API organization’s usage tier. Google, xAI, and open-weight models work at every tier; OpenAI and Anthropic models need Tier 1 or Tier 2. See Access by Usage Tier. Use the Orchestrator API for direct model access with your own prompts and tools. For web-grounded answers with citations, use the Agent API. For ranked web results to feed a model you already run, use the Search API. For probabilities on yes/no, choice, and rating questions, use the Decisions API.

Authentication

Create an API key in the API Console and set it as an environment variable:
The examples below pass the key through the SDK’s api_key parameter, because the OpenAI and Anthropic SDKs otherwise read OPENAI_API_KEY and ANTHROPIC_API_KEY. Direct HTTP requests send it as Authorization: Bearer $PERPLEXITY_API_KEY.

Installation

Use the OpenAI SDK, the Anthropic SDK, or both:

Chat Completions

Point the OpenAI SDK at the Orchestrator API base URL and pass the model’s full ID:
reasoning_content is shortened above; the full text was 922 reasoning tokens. GLM models reason by default. Reasoning & Caching covers how to set the effort and where each format reports reasoning and cached tokens. The response echoes the model ID you requested, and usage is billed at that model’s published rates.

Streaming

Set stream: true to receive tokens as server-sent events. To get token usage with a streamed Chat Completions response, also set stream_options: {"include_usage": true}. Usage then arrives in a final chunk before data: [DONE]. The Responses and Messages formats also accept stream: true and stream their own native event types; see the API reference for each.

OpenAI Responses

Use client.responses.create() with the same base URL when your integration uses the OpenAI Responses format. Include the full conversation in input on each request:

Anthropic Messages

The same models are available in the Anthropic Messages format. Configure the Anthropic SDK with https://api.perplexity.ai/orchestrator as the base URL and your Perplexity API key:

Model Routing

Set model to perplexity/auto to have a decision model pick the model for each request, either from the default policy or from routes you define. The response’s model field names the model that served the request, and the x-perplexity-autoroute-* response headers report the decision. The default policy uses OpenAI models that require Tier 1; at Tier 0, pass custom routes that name models your tier can use. Routing & Reliability covers the default policy, custom routes, route rules, headers, and errors.

Next Steps

Models & Pricing

The model catalog with context windows, per-token rates, and usage tiers.

Reasoning & Caching

Set reasoning effort, carry reasoning across turns, and cache prompts in each format.

Routing & Reliability

Model routing with perplexity/auto, deployment selection, rate limits, and failover.

API Reference

Request and response schemas, starting with Chat Completions.
For help, ask in the Perplexity community.