This guide shows how to use Perplexity's Agent API as a unified gateway to models from OpenAI, Anthropic, Google, xAI, and Perplexity — all through a single API key with transparent token-based pricing. You will learn how to route to specific providers, build fallback chains for high availability, compare responses across models, and dynamically discover available models via the `/v1/models` endpoint.

:::callout{intent="info"}
Perplexity provides third-party model access with transparent token-based pricing, consolidated on a single bill. See [Agent API Models](/guides/agent-api-models) for the full list and current rates.
:::

## Prerequisites

Install the Perplexity SDK:

:::code-group
```bash Python theme={null}
pip install perplexityai
```

```bash TypeScript theme={null}
npm install @perplexity-ai/perplexity_ai
```
:::

If you don't have an API key yet:

:::card{title="Get your Perplexity API Key" href="https://perplexity.ai/account/api" icon="key" cta="Click here" horizontal="true" arrow="true"}
Navigate to the **API Keys** tab in the API Portal and generate a new key.
:::

Then export your API key as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key"
```

## Why Multi-Provider?

| Benefit                 | Details                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------- |
| **Single API key**      | Access OpenAI, Anthropic, Google, xAI, and Perplexity models without separate accounts |
| **Transparent pricing** | Third-party model usage is charged at published model rates                            |
| **Unified format**      | Same request/response format across all providers                                      |
| **Built-in fallback**   | The `models` parameter tries providers in order until one succeeds                     |
| **Tool compatibility**  | `web_search`, `fetch_url`, and custom functions work with all models                   |

## Available Models

Use the `/v1/models` endpoint to discover all available models dynamically.

:::code-group
```python Python theme={null}
import requests
import os

resp = requests.get(
    "https://api.perplexity.ai/v1/models",
    headers={"Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}"}
)
models = resp.json()["data"]

# Group by provider
providers = {}
for model in models:
    provider = model["id"].split("/")[0] if "/" in model["id"] else "perplexity"
    providers.setdefault(provider, []).append(model["id"])

for provider, model_ids in sorted(providers.items()):
    print(f"\n{provider}:")
    for mid in model_ids:
        print(f"  {mid}")
```

```typescript TypeScript theme={null}
const resp = await fetch("https://api.perplexity.ai/v1/models", {
    headers: { Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY}` },
});
const models = (await resp.json()).data;

// Group by provider
const providers: Record<string, string[]> = {};
for (const model of models) {
    const provider = model.id.includes("/") ? model.id.split("/")[0] : "perplexity";
    (providers[provider] ??= []).push(model.id);
}

for (const [provider, ids] of Object.entries(providers).sort()) {
    console.log(`\n${provider}:`);
    for (const id of ids) console.log(`  ${id}`);
}
```

```bash curl theme={null}
curl -s "https://api.perplexity.ai/v1/models" \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" | python3 -m json.tool
```
:::

Key models across providers:

| Provider       | Models                                                                                   | Best For                            |
| -------------- | ---------------------------------------------------------------------------------------- | ----------------------------------- |
| **OpenAI**     | `openai/gpt-5.6-sol`, `openai/gpt-5.6-terra`, `openai/gpt-5.6-luna`, `openai/gpt-5.5`    | General reasoning, code, analysis   |
| **Anthropic**  | `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `anthropic/claude-haiku-4-5` | Long context, instruction following |
| **Google**     | `google/gemini-3.1-flash-lite`, `google/gemini-3.1-pro-preview`                          | Multimodal, fast inference          |
| **xAI**        | `xai/grok-4.20-non-reasoning`                                                            | Fast responses, conversational      |
| **Perplexity** | `perplexity/sonar`                                                                       | Search-grounded answers             |

## Routing to a Specific Provider

Use the `model` parameter to target a specific provider's model.

:::code-group
```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Route to OpenAI
openai_response = client.responses.create(
    model="openai/gpt-5.6-terra",
    input="Explain the difference between TCP and UDP.",
    max_output_tokens=500,
)
print(f"OpenAI: {openai_response.output_text[:200]}...")

# Route to Anthropic
anthropic_response = client.responses.create(
    model="anthropic/claude-sonnet-4-6",
    input="Explain the difference between TCP and UDP.",
    max_output_tokens=500,
)
print(f"Anthropic: {anthropic_response.output_text[:200]}...")

# Route to Google
google_response = client.responses.create(
    model="google/gemini-3.1-flash-lite",
    input="Explain the difference between TCP and UDP.",
    max_output_tokens=500,
)
print(f"Google: {google_response.output_text[:200]}...")
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

// Route to OpenAI
const openaiResponse = await client.responses.create({
    model: "openai/gpt-5.6-terra",
    input: "Explain the difference between TCP and UDP.",
    max_output_tokens: 500,
});
console.log(`OpenAI: ${openaiResponse.output_text.slice(0, 200)}...`);

// Route to Anthropic
const anthropicResponse = await client.responses.create({
    model: "anthropic/claude-sonnet-4-6",
    input: "Explain the difference between TCP and UDP.",
    max_output_tokens: 500,
});
console.log(`Anthropic: ${anthropicResponse.output_text.slice(0, 200)}...`);

// Route to Google
const googleResponse = await client.responses.create({
    model: "google/gemini-3.1-flash-lite",
    input: "Explain the difference between TCP and UDP.",
    max_output_tokens: 500,
});
console.log(`Google: ${googleResponse.output_text.slice(0, 200)}...`);
```
:::

## Model Fallback Chains

The `models` parameter accepts an array of up to 5 models. The API tries each in order and returns the first successful response. This is ideal for production systems where availability matters.

:::code-group
```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Primary: OpenAI, fallback: Anthropic, then Google
response = client.responses.create(
    models=[
        "openai/gpt-5.6-terra",
        "anthropic/claude-sonnet-4-6",
        "google/gemini-3.1-flash-lite",
    ],
    input="What are the key principles of zero-trust security?",
    tools=[{"type": "web_search"}],
)

print(f"Model used: {response.model}")
print(f"Response: {response.output_text[:300]}...")
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
    models: [
        "openai/gpt-5.6-terra",
        "anthropic/claude-sonnet-4-6",
        "google/gemini-3.1-flash-lite",
    ],
    input: "What are the key principles of zero-trust security?",
    tools: [{ type: "web_search" }],
});

console.log(`Model used: ${response.model}`);
console.log(`Response: ${response.output_text.slice(0, 300)}...`);
```
:::

:::callout{intent="tip"}
Order your fallback chain by preference: put your primary model first, then alternatives in decreasing order of preference. The API returns the response from the first model that succeeds.
:::

## Comparing Responses Across Providers

Send the same prompt to multiple models and compare quality, latency, and cost.

:::code-group
```python Python theme={null}
import time
import json
from perplexity import Perplexity

client = Perplexity()

MODELS = [
    "openai/gpt-5.6-terra",
    "anthropic/claude-sonnet-4-6",
    "google/gemini-3.1-flash-lite",
    "xai/grok-4.20-non-reasoning",
    "perplexity/sonar",
]

prompt = "What are the three most important design patterns in microservices architecture?"

results = []
for model in MODELS:
    print(f"Querying {model}...")
    start = time.time()
    try:
        response = client.responses.create(
            model=model,
            input=prompt,
            max_output_tokens=800,
        )
        elapsed = time.time() - start
        results.append({
            "model": model,
            "latency": round(elapsed, 2),
            "tokens": response.usage.output_tokens,
            "cost": response.usage.cost.total_cost,
            "preview": response.output_text[:150].replace("\n", " "),
        })
    except Exception as e:
        results.append({"model": model, "error": str(e)})

# Display comparison
print(f"\n{'Model':<42} {'Latency':>8} {'Tokens':>7} {'Cost':>10}")
print("-" * 70)
for r in results:
    if "error" in r:
        print(f"{r['model']:<42} {'ERROR':>8}")
    else:
        print(f"{r['model']:<42} {r['latency']:>7.2f}s {r['tokens']:>7} ${r['cost']:.5f}")
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const MODELS = [
    "openai/gpt-5.6-terra",
    "anthropic/claude-sonnet-4-6",
    "google/gemini-3.1-flash-lite",
    "xai/grok-4.20-non-reasoning",
    "perplexity/sonar",
];

const prompt = "What are the three most important design patterns in microservices architecture?";

const results: any[] = [];
for (const model of MODELS) {
    console.log(`Querying ${model}...`);
    const start = Date.now();
    try {
        const response = await client.responses.create({
            model,
            input: prompt,
            max_output_tokens: 800,
        });
        const elapsed = (Date.now() - start) / 1000;
        results.push({
            model,
            latency: elapsed.toFixed(2),
            tokens: response.usage.output_tokens,
            cost: response.usage.cost.total_cost,
            preview: response.output_text.slice(0, 150).replace(/\n/g, " "),
        });
    } catch (e: any) {
        results.push({ model, error: e.message });
    }
}

console.log(`\n${"Model".padEnd(42)} ${"Latency".padStart(8)} ${"Tokens".padStart(7)} ${"Cost".padStart(10)}`);
console.log("-".repeat(70));
for (const r of results) {
    if (r.error) {
        console.log(`${r.model.padEnd(42)} ${"ERROR".padStart(8)}`);
    } else {
        console.log(`${r.model.padEnd(42)} ${(r.latency + "s").padStart(8)} ${String(r.tokens).padStart(7)} ${"$" + r.cost.toFixed(5)}`);
    }
}
```
:::

## Task-Based Model Routing

Different tasks suit different models. Build a router that picks the best model for each task type.

:::code-group
```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Route based on task characteristics
MODEL_ROUTING = {
    "code": "anthropic/claude-sonnet-4-6",      # Strong at code generation
    "analysis": "openai/gpt-5.6-terra",               # Strong at structured analysis
    "fast_chat": "xai/grok-4.20-non-reasoning",  # Lowest latency
    "research": "perplexity/sonar",              # Built-in search grounding
    "multimodal": "google/gemini-3.1-flash-lite",  # Vision + speed
}


def route_request(task_type: str, prompt: str, **kwargs) -> dict:
    """Route a request to the optimal model based on task type."""
    model = MODEL_ROUTING.get(task_type)
    if not model:
        raise ValueError(f"Unknown task type: {task_type}. Options: {list(MODEL_ROUTING.keys())}")

    # Add web_search for research tasks
    tools = kwargs.pop("tools", None)
    if task_type == "research" and tools is None:
        tools = [{"type": "web_search"}]

    response = client.responses.create(
        model=model,
        input=prompt,
        tools=tools,
        **kwargs,
    )

    return {
        "model": response.model,
        "task_type": task_type,
        "output": response.output_text,
        "cost": response.usage.cost.total_cost,
    }


# Code task → Anthropic
code_result = route_request(
    "code",
    "Write a Python function that implements binary search on a sorted list.",
    max_output_tokens=500,
)
print(f"[{code_result['task_type']}] via {code_result['model']} (${code_result['cost']:.5f})")
print(code_result["output"][:200])

# Research task → Perplexity Sonar
research_result = route_request(
    "research",
    "What were the key announcements at the latest WWDC?",
)
print(f"\n[{research_result['task_type']}] via {research_result['model']} (${research_result['cost']:.5f})")
print(research_result["output"][:200])
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const MODEL_ROUTING: Record<string, string> = {
    code: "anthropic/claude-sonnet-4-6",
    analysis: "openai/gpt-5.6-terra",
    fast_chat: "xai/grok-4.20-non-reasoning",
    research: "perplexity/sonar",
    multimodal: "google/gemini-3.1-flash-lite",
};

async function routeRequest(taskType: string, prompt: string, options: Record<string, any> = {}) {
    const model = MODEL_ROUTING[taskType];
    if (!model) throw new Error(`Unknown task type: ${taskType}`);

    const tools = options.tools ?? (taskType === "research" ? [{ type: "web_search" }] : undefined);

    const response = await client.responses.create({
        model,
        input: prompt,
        tools,
        ...options,
    });

    return {
        model: response.model,
        taskType,
        output: response.output_text,
        cost: response.usage.cost.total_cost,
    };
}

// Code task → Anthropic
const codeResult = await routeRequest("code", "Write a Python function that implements binary search on a sorted list.", { max_output_tokens: 500 });
console.log(`[${codeResult.taskType}] via ${codeResult.model} ($${codeResult.cost.toFixed(5)})`);
console.log(codeResult.output.slice(0, 200));

// Research task → Perplexity Sonar
const researchResult = await routeRequest("research", "What were the key announcements at the latest WWDC?");
console.log(`\n[${researchResult.taskType}] via ${researchResult.model} ($${researchResult.cost.toFixed(5)})`);
console.log(researchResult.output.slice(0, 200));
```
:::

## Combining Multi-Provider with Tools

All models accessed through the Agent API support the same tool interface — `web_search`, `fetch_url`, and custom functions work identically regardless of provider.

:::code-group
```python Python theme={null}
from perplexity import Perplexity
import json

client = Perplexity()

tools = [
    {"type": "web_search"},
    {
        "type": "function",
        "name": "calculate_roi",
        "description": "Calculate return on investment given initial cost and revenue.",
        "parameters": {
            "type": "object",
            "properties": {
                "initial_cost": {"type": "number", "description": "Initial investment in USD"},
                "annual_revenue": {"type": "number", "description": "Expected annual revenue in USD"},
                "years": {"type": "integer", "description": "Number of years"},
            },
            "required": ["initial_cost", "annual_revenue", "years"],
        },
    },
]


def calculate_roi(initial_cost: float, annual_revenue: float, years: int) -> dict:
    total_revenue = annual_revenue * years
    roi = ((total_revenue - initial_cost) / initial_cost) * 100
    return {"roi_percent": round(roi, 2), "total_revenue": total_revenue, "net_profit": total_revenue - initial_cost}


# Use Anthropic Claude with web search + custom function
response = client.responses.create(
    model="anthropic/claude-sonnet-4-6",
    tools=tools,
    input=(
        "Research the average cost to deploy a 100kW commercial solar installation in 2026, "
        "then calculate the 10-year ROI assuming $18,000 annual energy savings."
    ),
)

# Handle function calls
while any(item.type == "function_call" for item in response.output):
    next_input = [item.model_dump() for item in response.output]
    for item in response.output:
        if item.type == "function_call":
            args = json.loads(item.arguments)
            result = calculate_roi(**args)
            next_input.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result),
            })
    response = client.responses.create(
        model="anthropic/claude-sonnet-4-6",
        tools=tools,
        input=next_input,
    )

print(response.output_text)
```
:::

## Dynamic Model Discovery

Build applications that automatically adapt to newly available models by querying the `/v1/models` endpoint at startup.

:::code-group
```python Python theme={null}
import requests
import os
from perplexity import Perplexity

client = Perplexity()


def discover_models() -> dict[str, list[str]]:
    """Fetch available models and group by provider."""
    resp = requests.get(
        "https://api.perplexity.ai/v1/models",
        headers={"Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}"},
    )
    resp.raise_for_status()
    models = resp.json()["data"]

    providers = {}
    for model in models:
        provider = model["id"].split("/")[0] if "/" in model["id"] else "perplexity"
        providers.setdefault(provider, []).append(model["id"])
    return providers


def build_fallback_chain(providers: dict[str, list[str]], preferred_order: list[str]) -> list[str]:
    """Build a fallback chain from available models, picking one per provider."""
    chain = []
    for provider in preferred_order:
        if provider in providers and providers[provider]:
            chain.append(providers[provider][0])  # Pick first available model
    return chain[:5]  # Max 5 models in fallback chain


# Discover and build chain
available = discover_models()
print(f"Available providers: {list(available.keys())}")

chain = build_fallback_chain(available, ["openai", "anthropic", "google", "xai", "perplexity"])
print(f"Fallback chain: {chain}")

# Use the dynamic chain
response = client.responses.create(
    models=chain,
    input="Summarize the latest developments in AI regulation worldwide.",
    tools=[{"type": "web_search"}],
)
print(f"\nModel used: {response.model}")
print(response.output_text[:300])
```

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

async function discoverModels(): Promise<Record<string, string[]>> {
    const resp = await fetch("https://api.perplexity.ai/v1/models", {
        headers: { Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY}` },
    });
    const models = (await resp.json()).data;

    const providers: Record<string, string[]> = {};
    for (const model of models) {
        const provider = model.id.includes("/") ? model.id.split("/")[0] : "perplexity";
        (providers[provider] ??= []).push(model.id);
    }
    return providers;
}

function buildFallbackChain(providers: Record<string, string[]>, preferredOrder: string[]): string[] {
    const chain: string[] = [];
    for (const provider of preferredOrder) {
        if (providers[provider]?.length) {
            chain.push(providers[provider][0]);
        }
    }
    return chain.slice(0, 5);
}

const available = await discoverModels();
console.log(`Available providers: ${Object.keys(available).join(", ")}`);

const chain = buildFallbackChain(available, ["openai", "anthropic", "google", "xai", "perplexity"]);
console.log(`Fallback chain: ${chain.join(" → ")}`);

const response = await client.responses.create({
    models: chain,
    input: "Summarize the latest developments in AI regulation worldwide.",
    tools: [{ type: "web_search" }],
});

console.log(`\nModel used: ${response.model}`);
console.log(response.output_text.slice(0, 300));
```
:::

:::callout{intent="info"}
The `/v1/models` endpoint returns the current list of supported models. Query it at application startup or cache it with a TTL to stay current as new models are added.
:::

## Next Steps

::::card-grid
:::card{title="Agent API Models" href="/guides/agent-api-models" icon="brain"}
Full list of available models, capabilities, and pricing.
:::

:::card{title="Model Fallback" href="/guides/agent-api-model-fallback" icon="square-rounded-arrow-down"}
Deep dive into fallback chain configuration and behavior.
:::

:::card{title="Model Comparison Example" href="/guides/cookbook-2-cookbook-examples-model-comparison" icon="chart-bar"}
CLI tool for benchmarking models side-by-side.
:::

:::card{title="Presets" href="/guides/agent-api-presets" icon="settings"}
Use presets like `low` for optimized defaults.
:::
::::

## Related pages

- [RAG with Perplexity Embeddings](./cookbook-2-cookbook-articles-embeddings-rag.md)
- [Streaming Citation Parsing](./cookbook-2-cookbook-articles-streaming-citations.md)
- [Structured Output Extraction](./cookbook-2-cookbook-articles-structured-output-extraction.md)
- [Academic and Scholarly Search](./cookbook-2-cookbook-articles-academic-search.md)
- [Deep Research Workflows](./cookbook-2-cookbook-articles-async-deep-research.md)
- [Search Domain Filtering Patterns](./cookbook-2-cookbook-articles-search-domain-filtering.md)
- [VC Investment Memo Agent with LangGraph](./cookbook-2-cookbook-articles-langchain-vc-memo-agent.md)
- [Daily AI Stock News PDF with Skills](./cookbook-2-cookbook-articles-agent-skills.md)
- [Daily News Digest with LLM Deduplication](./cookbook-2-cookbook-articles-news-dedupe-digest.md)
- [Build an incident responder with Profiles, Skills, and Managed Connectors](./cookbook-2-cookbook-articles-incident-responder.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.