perplexity

What this skill does

# Perplexity API

Build AI applications with real-time web search and grounded responses.

## Quick Navigation

- Models & pricing: `references/models.md`
- Search API patterns: `references/search-api.md`
- Chat completions guide: `references/chat-completions.md`
- Browser sessions API: `references/browser.md`
- Embeddings API: `references/embeddings.md`
- Structured outputs: `references/structured-outputs.md`
- Filters (domain/language/date/location): `references/filters.md`
- Media (images/videos/attachments): `references/media.md`
- Pro Search: `references/pro-search.md`
- Prompting best practices: `references/prompting.md`

## When to Use

- Need AI responses grounded in current web data
- Building search-powered applications
- Research tools requiring citations
- Real-time Q&A with source verification
- Document/image analysis with web context

## Installation

Install: `pip install perplexityai` (Python) or `npm install @perplexityai/perplexity` (TypeScript/JavaScript).

## Authentication

```bash
# macOS/Linux
export PERPLEXITY_API_KEY="your_api_key_here"

# Windows
setx PERPLEXITY_API_KEY "your_api_key_here"
```

SDK auto-reads `PERPLEXITY_API_KEY` environment variable.

## Quick Start — Chat Completion

```python
from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What is the latest news on AI?"}]
)

print(completion.choices[0].message.content)
```

**Note (v0.28.0):** The Python client includes a custom JSON encoder to support additional types in request payloads.

## Quick Start — Search API

```python
from perplexity import Perplexity

client = Perplexity()

search = client.search.create(
    query="artificial intelligence trends 2024",
    max_results=5
)

for result in search.results:
    print(f"{result.title}: {result.url}")
```

## Release Highlights (0.34.1 -> 0.36.0)

- **Streaming**: `responses.create` now yields named SSE events and discriminates the `ResponseStreamEvent` union, which matters for typed stream consumers.
- **Search API**: `search_context_size` was briefly exposed on `search.create` and then removed in `0.35.1`; keep search-context sizing on chat/web-search options, not the raw Search API.
- **Background responses**: the SDK adds background-task support and `responses.retrieve`, so long-running response workflows can be polled instead of only streamed inline.
- **Reasoning effort**: `xhigh` is available where the API supports reasoning-effort controls.
- **Sandbox tool**: `0.36.0` adds the Responses API sandbox built-in tool; gate it like other executable/tooling surfaces.

## Model Selection Guide

| Model                 | Use Case                       | Cost    |
| --------------------- | ------------------------------ | ------- |
| `sonar`               | Quick facts, simple Q&A        | Lowest  |
| `sonar-pro`           | Complex queries, research      | Medium  |
| `sonar-reasoning-pro` | Multi-step reasoning, analysis | Medium  |
| `sonar-deep-research` | Exhaustive research, reports   | Highest |

## Key Patterns

### Streaming Responses

```python
stream = client.chat.completions.create(
    messages=[{"role": "user", "content": "Explain quantum computing"}],
    model="sonar",
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### Multi-Turn Conversation

```python
messages = [
    {"role": "system", "content": "You are a research assistant."},
    {"role": "user", "content": "What causes climate change?"},
    {"role": "assistant", "content": "Climate change is caused by..."},
    {"role": "user", "content": "What are the solutions?"}
]

completion = client.chat.completions.create(messages=messages, model="sonar")
```

### Web Search Options

```python
completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "Latest renewable energy news"}],
    model="sonar",
    web_search_options={
        "search_recency_filter": "week",
        "search_domain_filter": ["energy.gov", "iea.org"]
    }
)
```

### Pro Search (Multi-Step Research)

```python
# REQUIRES stream=True
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Research solar panel ROI"}],
    search_type="pro",
    stream=True
)

for chunk in completion:
    print(chunk.choices[0].delta.content or "", end="")
```

### Image Attachment

```python
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
    }]
)
```

### File Attachment (PDF Analysis)

```python
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize this document"},
            {"type": "file_url", "file_url": {"url": "https://example.com/report.pdf"}}
        ]
    }]
)
```

### Return Images in Response

```python
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Mount Everest photos"}],
    return_images=True,
    image_format_filter=["jpg", "png"]
)
```

### Domain Filtering (Search API)

```python
# Allowlist: include only these domains
search = client.search.create(
    query="climate research",
    search_domain_filter=["science.org", "nature.com"]
)

# Denylist: exclude these domains
search = client.search.create(
    query="tech news",
    search_domain_filter=["-reddit.com", "-pinterest.com"]
)
```

### Multi-Query Search

```python
search = client.search.create(
    query=[
        "AI trends 2024",
        "machine learning healthcare",
        "neural networks applications"
    ],
    max_results=5
)

for i, query_results in enumerate(search.results):
    print(f"Query {i+1} results:")
    for result in query_results:
        print(f"  {result.title}")
```

### Structured Outputs (JSON Schema)

```python
from pydantic import BaseModel

class ContactInfo(BaseModel):
    email: str
    phone: str

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Find contact for Tesla IR"}],
    response_format={
        "type": "json_schema",
        "json_schema": {"schema": ContactInfo.model_json_schema()}
    }
)

contact = ContactInfo.model_validate_json(completion.choices[0].message.content)
```

### Async Operations

```python
import asyncio
from perplexity import AsyncPerplexity

async def main():
    async with AsyncPerplexity() as client:
        tasks = [
            client.search.create(query="AI news"),
            client.search.create(query="tech trends")
        ]
        results = await asyncio.gather(*tasks)

asyncio.run(main())
```

### Rate Limit Handling

```python
import time
from perplexity import RateLimitError

def search_with_retry(client, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.search.create(query=query)
        except RateLimitError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise
```

## Response Parameters

| Parameter           | Default | Description                     |
| ------------------- | ------- | ------------------------------- |
| `temperature`       | 0.7     | Creativity (0-2)                |
| `max_tokens`        | varies  | Response length limit           |
| `top_p`             | 0.9     | Nucleus sampling                |
| `presence_penalty`  | 0       | Reduce repetition (-2 to 2)     |
| `frequency_penalty` | 0       | Reduce word frequency (-2 to 2) |

## Search API Parameters

| Parameter                | Description                             |
| -