模型与多模态实用指南2026年10月26日Cxj

Perplexity AI API：访问、定价、集成与生产指南

一份基于来源的指南，帮助您选择合适的 Perplexity API 接口、正确集成、预估成本，并在生产环境中安全运行。

Perplexity AI API：访问、定价、集成与生产指南

最后一次根据 Perplexity 文档验证：2026 年 10 月 24 日。

Perplexity AI API 不再是一个没有区分的“搜索聊天 API”。它现在为基于 Web 的智能体响应、开放权重模型路由、原始搜索、嵌入和类型化决策提供了不同的接口。请在编写代码之前选择与任务匹配的接口：这将决定端点、SDK 方法、计费单位、速率限制，以及你在生产环境中需要记录的内容。

对于大多数新的研究或助手功能，请从 Agent API 开始。它遵循 OpenAI Responses 格式，可以使用 Web 搜索，并返回带有来源的结构化输出。当你现有的 OpenAI Chat Completions 代码需要访问其开放权重模型目录时，请使用 Orchestrator API。当你需要不含 LLM 答案的排序结果时，请使用 Search。

简要答案：应使用哪个 Perplexity API？

需求	使用	你将获得的内容	集成形式
带有来源、工具或多步骤工作流的研究型答案	Agent API	结构化 Responses 输出，包括可识别来源的结果项	`POST /v1/agent` 或可接受的 `/v1/responses` 别名
通过 OpenAI Chat Completions 风格客户端访问开放权重模型	Orchestrator API	Chat Completions 风格的响应	`POST /orchestrator/v1/chat/completions`
将由你自己的管道处理的排序 Web 结果	Search API	原始搜索结果	`POST /search`
用于语义搜索、RAG 或分类的向量	Embeddings API	嵌入	Perplexity 嵌入端点/SDK
经校准的是/否、多项选择或量规决策	Decisions API	类型化答案加概率	Decisions 端点/SDK

这一区分是最重要的 Perplexity AI API 设计选择。Perplexity 当前的概述将 Agent API 描述为兼容 OpenAI Responses、基于 Web 的 API；其 Orchestrator API 则是面向托管开放权重模型的独立兼容接口。阅读 Perplexity 的概述。

获取 Perplexity AI API 访问权限

在 Perplexity API Console 中创建账户。
在 API Keys 页面生成密钥。
仅将其存储在服务器或部署密钥管理器中。
在运行时环境中设置 PERPLEXITY_API_KEY，而不是在浏览器代码、git、示例或日志中设置。
在发送生产流量前添加计费。Perplexity 记录了无需订阅的按量付费 API 计费方式；上线前请查看实时定价页面，因为模型和工具费率可能会变化。

在 macOS 或 Linux 上，设置密钥时不要打印它：

export PERPLEXITY_API_KEY="replace-in-your-secret-manager"
test -n "$PERPLEXITY_API_KEY" && echo "PERPLEXITY_API_KEY is set"

最后一条命令会特意确认密钥是否存在，而不暴露其值。Perplexity 明确建议不要在终端输出中打印密钥，甚至不要打印密钥片段。对于应用程序的其余部分，也应遵循同一规则：对 Authorization 标头进行脱敏、轮换已泄露的密钥，并为每个环境分配独立凭据。在添加客户流量前，请将此做法与安全的 API 密钥管理工作流配合使用。

使用 OpenAI SDK 集成 Agent API

当你的产品需要基于 Web 的答案、引用、工具使用，或可跨轮次继续的响应时，Agent API 是合适的 Perplexity AI API 接口。Perplexity 将 OpenAI SDK 配置记录为 base_url="https://api.perplexity.ai/v1"，并使用 client.responses.create()。

import os
from openai import OpenAI

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

response = client.responses.create(
    model="perplexity/sonar",
    input="What changed in the last 30 days for this topic? Cite primary sources.",
    tools=[{"type": "web_search"}],
    max_output_tokens=600,
)

print(response.output_text)

规范端点是 POST /v1/agent；OpenAI SDK 会发送 POST /v1/responses，Perplexity 将其作为别名接受。这在 Responses 层兼容，并不承诺每个 Chat Completions 选项都能干净地映射。Perplexity 的 OpenAI 兼容性指南是受支持请求和响应字段的权威来源。

这里有两个重要的生产细节：

Web 搜索需要主动启用。仅包含 model 和 input 的请求会使用模型知识，且不返回引用；当时效性和来源很重要时，请使用 effort 级别或 web_search 工具。
在应用程序边界中保留结构化的 output，而不只是 output_text。引用、工具活动、状态、用量和响应 ID 都是运营数据，而不是 UI 的装饰。

在将模型标识符硬编码之前，请在部署工作流中查询 GET /v1/models，或查看当前的 Agent API 模型目录。Perplexity 以与 OpenAI 兼容的格式记录了该端点，因此它适用于允许列表和发布检查。

当您需要 Chat Completions 兼容性时，使用 Orchestrator API

Perplexity AI API 针对另一项任务提供了第二条兼容 OpenAI 的路径。Orchestrator API 使用 Chat Completions 格式，并采用不同的基础 URL：

import os
from openai import OpenAI

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

completion = client.chat.completions.create(
    model=os.environ["PPLX_ORCHESTRATOR_MODEL"],
    max_tokens=500,
    messages=[
        {"role": "user", "content": "Summarize these notes in five bullets."}
    ],
)

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

请使用环境变量存储模型 ID，并在 CI 或发布检查中验证它。目录可用性、别名和价格表的变化频率，高于您的应用代码应有的变化频率。需要避免的关键错误是将 Agent API 和 Orchestrator API 视为可以互换：

Agent API：https://api.perplexity.ai/v1 + responses.create()。
Orchestrator API：https://api.perplexity.ai/orchestrator/v1 + chat.completions.create()。

如果您的目标是获得带引用的最新答案，不要仅仅因为该客户端很熟悉就切换到 Chat Completions。如果您的目标是针对托管开放权重目录进行可直接替换的 OpenAI Chat Completions 迁移，请不要将其指向 Agent 基础 URL。Perplexity 快速入门展示了这两种模式。

Perplexity AI API 定价：计算整个请求

为 Perplexity AI API 制定预算的实用方法，是将令牌费用与工具或请求费用分开。确切费率表是实时且因模型而异的，因此应将定价页面作为部署输入，而不是每季度复制一次到幻灯片中的数字。

服务面	计费模型	生产环境影响
Orchestrator API	按模型计收输入、输出和缓存读取令牌费率；推理令牌按输出费率计费；无按请求收费	根据实测的输入、输出和缓存令牌进行估算。
Agent API 模型	按所选提供商/模型进行透明的基于令牌的定价	为每个用户可见请求记录返回的用量和所选模型。
Agent `web_search`	标准：$0.0025/次调用；快速搜索：$0.001/次调用	应有意识地使用 Web 访问；它是一项单独的成本。
Agent `fetch_url`	$0.0005/次调用	限制代理循环中的 URL 获取次数。
Agent 沙盒	$0.03/会话，另加 SDK 搜索查询费用	将沙盒会话视为独立资源。
Search API	每 1,000 个成功的标准请求 $5.00；每 1,000 个快速搜索请求 $1.00	一个最多包含五个查询的请求，计为一个成功请求计费单位。

上述费率已于 2026 年 10 月 24 日核查。在设定利润率、客户配额或预算警报之前，应再次查看官方定价页面和 Agent API 模型目录。

一个有用的规划公式是：

request_cost =
  (input_tokens / 1,000,000 × input_rate) +
  (output_tokens / 1,000,000 × output_rate) +
  (cache_read_tokens / 1,000,000 × cache_read_rate) +
  tool_invocations × tool_rate +
  search_requests × search_request_rate

不要仅根据输出令牌估算经过研究的答案。Agent 工作流可能使用输入上下文、输出/推理令牌和工具调用。请将每个维度与您的租户 ID、功能名称、请求的模型、最终模型及响应 ID 一同存储。同一事件模型使AI 模型价格比较比仅比较目录价格更有意义。

构建可用于生产环境的 Perplexity AI API 工作流

1. 将 API 服务面作为明确的产品决策

为每个服务面定义一个小型适配器，例如 perplexity_agent、perplexity_search 和 perplexity_orchestrator。在决定如何处理引用、搜索结果、用量和工具事件之前，不要将它们不同的响应类型隐藏在通用的 chat() 函数之后。

对于面向客户的研究答案，您的适配器至少应返回：

answer_text, citations, response_id, status, requested_model,
served_model, input_tokens, output_tokens, tool_calls, cost, latency_ms

对于原始 Search，请将结果与任何后续综合内容分开返回。这样既能保留来源追溯信息，也能让您在不悄然更改搜索提供商的情况下更换写作模型。

2. 将引用视为必须保留的数据

当您的 Perplexity AI API 请求使用网页搜索时，请在其所支持的主张旁展示引用来源。保存返回的来源 URL、提供时的标题，以及用于生成答案的响应 ID。对于研究功能、支持代理或内部决策工作流而言，只有友好的回答而没有可检查的来源是不够的。

请在上线前确定您的策略：

对于事实性回答，您是否要求至少有一个一手来源？
如果没有任何引文支持某项陈述，您是否会将其移除？
用户能否在根据答案采取行动前打开被引用的 URL？
您会保留来源元数据和响应记录多长时间？

3. 为滚动速率窗口做好预算，而不是只看单一的“每分钟请求数”

Perplexity 的 Agent API 文档说明，整个组织范围内存在一个请求限额，由 Agent 调用、轮询、取消/恢复操作和文件下载共同使用。文档还说明了按模型划分的令牌限额，这些限额采用滚动的分钟和小时窗口。轮询并非免费：在较低层级中，每秒轮询一次异步请求可能会耗尽全部请求额度。

对于 429 响应，请遵守 Retry-After。对于与容量相关的 overloaded 错误，请采用带抖动的指数退避，并且仅当产品能够安全地接受不同模型时，才使用已文档化的备用列表。不要将身份验证、验证或配额配置错误当作暂时性错误来重试。有关当前阈值和响应语义，请参阅 Perplexity 的速率限制和使用层级指南。

有界重试策略的伪代码：

for attempt in range(3):
    try:
        return call_perplexity()
    except RateLimitError as error:
        wait_seconds = retry_after_or_jittered_backoff(error, attempt)
        sleep(wait_seconds)
    except TransientCapacityError:
        sleep(jittered_backoff(attempt))

raise ServiceTemporarilyUnavailable()

保持较小的重试次数，使用端到端截止时间，并让调用方的备用状态可见。将缓慢的研究请求变成 90 秒加载转圈的重试，并不等于可靠性。

4. 记录足够的信息，以便同时调试成本、质量和时效性

跟踪请求 ID、端点系列、模型、推理强度级别、工具列表、首个令牌时间、完成时间、令牌维度、工具调用次数、HTTP 状态、重试次数以及安全的错误分类。对于带引用的响应，跟踪引用数量和来源域名。对于 Search，跟踪查询次数和结果数量。

这能为您提供证据，以回答如下问题：“延迟是否因为我们启用了搜索而上升？”、“哪个租户在沙盒会话上花费？”以及“备用方案是否提高了可用性却降低了引用覆盖率？” 如需更通用的架构，请参阅AI API 网关指南和LLM 速率限制指南。

5. 如果您有遗留代码，请规划 Sonar 迁移

Perplexity 当前的迁移指南指出，Sonar Chat Completions 支持已于 2026 年 9 月 27 日结束。它建议新项目使用 Agent API；同步和流式遗留请求正逐步被重新构建，而异步 Sonar 请求已不再受支持。如果您仍在调用 Sonar 端点，请现在测试 Agent API 适配器，而不要等到生产环境中发现异步中断。阅读迁移指南。

直接使用 Perplexity API，还是使用独立的多模型网关？

当功能依赖 Perplexity 特有的 Agent、Search、引用、推理强度级别或 API 行为时，请使用直接的 Perplexity AI API 集成。这样可以保持生产契约清晰。

仅针对该网关当前列为受支持的模型和端点使用独立的多模型网关。例如，Flatkey 为其受支持目录记录了一个与 OpenAI 兼容的基础 URL：https://router.flatkey.ai/v1，并提供请求级使用情况仪表板。在假定某个提供商或模型可用之前，应实时查看其公开模型目录。从 Flatkey API 快速入门开始。

对于两者都需要的团队，请使用两个明确的客户端：

需求	推荐的客户端边界
Perplexity 基于网络的研究和引用	直接使用 Perplexity Agent/Search 客户端
通过一个兼容的基础 URL 和集中的使用控制来访问受支持的非 Perplexity 模型	Flatkey 客户端
产品在一个工作流中同时需要两者	具有类型化适配器、独立模型允许列表和通用可观测性事件架构的应用层路由器

除非其当前文档明确支持该路由，否则不要通过另一项服务路由直接的 Perplexity 端点。重点不是强制让每个调用都经过同一层，而是保留您的功能实际依赖的能力和计费行为。

生产上线检查清单

[ ] 每项功能都经过有意选择，使用 Agent、Orchestrator、Search、Embeddings 或 Decisions。
[ ] API 密钥位于服务器端，按环境划分作用域，并且不出现在客户端包和日志中。
[ ] Agent 基础 URL（/v1）和 Orchestrator 基础 URL（/orchestrator/v1）没有混淆。
[ ] 在发布检查中验证模型 ID 和实时价格卡。
[ ] 仅在引用的新鲜度有用时，才明确启用 Web 搜索。
[ ] 带引用的响应会保留来源元数据和响应 ID。
[ ] 成本事件包含 token 维度以及工具或搜索调用次数。
[ ] 429 遵循 Retry-After；暂时性容量故障使用带抖动的有界指数退避。
[ ] 轮询采用退避，或替换为流式传输/重连行为。
[ ] 分阶段测试覆盖来源质量、延迟、成本、重试行为和用户可见的回退方案。

Perplexity AI API 常见问题

Perplexity AI API 与 OpenAI SDK 兼容吗？

是的，但请选择匹配的 API 形式。Agent API 在 https://api.perplexity.ai/v1 使用 OpenAI Responses 格式；Orchestrator API 在 https://api.perplexity.ai/orchestrator/v1 使用 Chat Completions。