Back to Details

perplexity

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Perplexity API

Perplexity API

Build AI applications with real-time web search and grounded responses.
构建具备实时网页搜索和基于事实响应能力的AI应用。

Quick Navigation

快速导航

  • Models & pricing: 
    references/models.md
  • Search API patterns: 
    references/search-api.md
  • Chat completions guide: 
    references/chat-completions.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
  • 模型与定价：
    references/models.md
  • Search API 模式：
    references/search-api.md
  • 聊天补全指南：
    references/chat-completions.md
  • Embeddings API：
    references/embeddings.md
  • 结构化输出：
    references/structured-outputs.md
  • 过滤器（域名/语言/日期/地区）：
    references/filters.md
  • 媒体（图片/视频/附件）：
    references/media.md
  • Pro Search：
    references/pro-search.md
  • 提示词最佳实践：
    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
  • 需要基于当前网络数据生成AI响应
  • 构建搜索驱动的应用
  • 需要引用来源的研究工具
  • 带来源验证的实时问答系统
  • 结合网络上下文的文档/图片分析

Installation

安装

bash
undefined
bash
undefined

Python

Python

pip install perplexityai
pip install perplexityai

TypeScript/JavaScript

TypeScript/JavaScript

npm install @perplexityai/perplexity
undefined
npm install @perplexityai/perplexity
undefined

Authentication

身份验证

bash
undefined
bash
undefined

macOS/Linux

macOS/Linux

export PERPLEXITY_API_KEY="your_api_key_here"
export PERPLEXITY_API_KEY="your_api_key_here"

Windows

Windows

setx PERPLEXITY_API_KEY "your_api_key_here"

SDK auto-reads `PERPLEXITY_API_KEY` environment variable.
setx PERPLEXITY_API_KEY "your_api_key_here"

SDK会自动读取`PERPLEXITY_API_KEY`环境变量。

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.
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)
注意（v0.28.0）： Python客户端包含自定义JSON编码器，支持在请求负载中添加更多类型。

Quick Start — Search API

快速入门 — 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}")
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}")

Model Selection Guide

模型选择指南

ModelUse CaseCost
sonar
Quick facts, simple Q&ALowest
sonar-pro
Complex queries, researchMedium
sonar-reasoning-pro
Multi-step reasoning, analysisMedium
sonar-deep-research
Exhaustive research, reportsHighest
模型适用场景成本
sonar
快速事实查询、简单问答最低
sonar-pro
复杂查询、研究类任务中等
sonar-reasoning-pro
多步骤推理、分析类任务中等
sonar-deep-research
深度研究、报告生成最高

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="")
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")
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"]
    }
)
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)

Pro Search（多步骤研究）

python
undefined
python
undefined

REQUIRES stream=True

必须设置 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="")
undefined
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="")
undefined

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"}}
        ]
    }]
)
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)

文件附件（PDF分析）

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"}}
        ]
    }]
)
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"]
)
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)

域名过滤（Search API）

python
undefined
python
undefined

Allowlist: include only these domains

白名单：仅包含这些域名

search = client.search.create( query="climate research", search_domain_filter=["science.org", "nature.com"] )
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"] )
undefined
search = client.search.create( query="tech news", search_domain_filter=["-reddit.com", "-pinterest.com"] )
undefined

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}")
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)

结构化输出（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)
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())
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
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

响应参数

ParameterDefaultDescription
temperature
0.7Creativity (0-2)
max_tokens
variesResponse length limit
top_p
0.9Nucleus sampling
presence_penalty
0Reduce repetition (-2 to 2)
frequency_penalty
0Reduce word frequency (-2 to 2)
参数默认值描述
temperature
0.7创造力（0-2）
max_tokens
可变响应长度限制
top_p
0.9核采样
presence_penalty
0减少重复度（-2至2）
frequency_penalty
0降低词频（-2至2）

Search API Parameters

Search API参数

ParameterDescription
max_results
1-20 results per query
max_tokens_per_page
Content extraction depth (default 2048)
country
ISO country code for regional results
search_domain_filter
Domain allowlist/denylist (max 20)
search_language_filter
ISO 639-1 language codes (max 10)
参数描述
max_results
每个查询返回1-20条结果
max_tokens_per_page
内容提取深度（默认2048）
country
区域结果对应的ISO国家代码
search_domain_filter
域名白名单/黑名单（最多20个）
search_language_filter
ISO 639-1语言代码（最多10个）

Pricing Quick Reference

定价快速参考

Search API: $5/1K requests (no token costs)
Sonar Models (per 1M tokens):
ModelInputOutput
sonar$1$1
sonar-pro$3$15
sonar-reasoning-pro$2$8
Request fees (per 1K requests): $5-$14 depending on search context size.
Search API： 每1000次请求5美元（无token费用）
Sonar模型（每100万token）：
模型输入输出
sonar1美元1美元
sonar-pro3美元15美元
sonar-reasoning-pro2美元8美元
请求费用（每1000次请求）：5-14美元，取决于搜索上下文大小。

Critical Prohibitions

�重要禁止事项

  • Do NOT request links/URLs in prompts (use 
    citations
    field instead — model will hallucinate URLs)
  • Do NOT use recursive JSON schemas (not supported)
  • Do NOT use 
    dict[str, Any]
    in Pydantic models for structured outputs
  • Do NOT mix allowlist and denylist in 
    search_domain_filter
  • Do NOT exceed 5 queries in multi-query search
  • Do NOT expect first request with new JSON schema to be fast (10-30s warmup)
  • Do NOT use Pro Search without 
    stream=True
    (will fail)
  • Do NOT send images to 
    sonar-deep-research
    (not supported)
  • Do NOT include 
    data:
    prefix for file attachments base64 (only for images)
  • Do NOT try to control search via prompts (use API parameters instead)
  • 请勿在提示词中要求链接/URL（请使用
    citations
    字段替代——模型会生成虚假URL）
  • 请勿使用递归JSON schema（不支持）
  • 请勿在用于结构化输出的Pydantic模型中使用
    dict[str, Any]
  • 请勿在
    search_domain_filter
    中同时混合白名单和黑名单
  • 多查询搜索中请勿超过5个查询
  • 请勿期望首次使用新JSON schema的请求速度快（预热需要10-30秒）
  • 使用Pro Search时必须设置
    stream=True
    （否则会失败）
  • 请勿向
    sonar-deep-research
    模型发送图片（不支持）
  • 文件附件的base64编码请勿添加
    data:
    前缀（仅图片允许）
  • 请勿通过提示词控制搜索逻辑（请使用API参数）

Error Handling

错误处理

python
import perplexity

try:
    completion = client.chat.completions.create(...)
except perplexity.BadRequestError as e:
    print(f"Invalid parameters: {e}")
except perplexity.RateLimitError:
    print("Rate limited, retry later")
except perplexity.APIStatusError as e:
    print(f"API error: {e.status_code}")
python
import perplexity

try:
    completion = client.chat.completions.create(...)
except perplexity.BadRequestError as e:
    print(f"Invalid parameters: {e}")
except perplexity.RateLimitError:
    print("Rate limited, retry later")
except perplexity.APIStatusError as e:
    print(f"API error: {e.status_code}")

OpenAI SDK Compatibility

OpenAI SDK兼容性

Perplexity supports OpenAI Chat Completions format. Use OpenAI client by pointing to Perplexity endpoint.
Perplexity支持OpenAI聊天补全格式。可通过指向Perplexity端点来使用OpenAI客户端。

Links

相关链接