如何获取 Perplexity API Key 并发出第一次 Sonar 请求

Perplexity API Key 是你每次请求 api.perplexity.ai 时携带的凭据。它标识你的项目、扣减预付余额，并决定你的速率限制档位。如果你以前没接触过，我们那篇《什么是 API Key》的入门文章讲了基础知识。本文只讲 Perplexity 特有的部分：创建账号、充值、生成 Key，以及用 curl、Python 和 Apifox 发出第一个带联网检索的 Sonar 请求。

开始之前先说明一个时间点。Perplexity 已经把 Sonar 迁到 Agent API，官方快速开始现在也指向那里。旧的 Sonar chat-completions 接口会继续可用到 2026 年 9 月 27 日，之后下线。下面所有示例都使用当前接口，并简单说明旧版写法，以防你还在维护老代码。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

开始前需要准备什么

一个 Perplexity 账号。Google、Apple、SSO 或免密码的邮箱登录都可以，它们会按邮箱地址归到同一个账号。
一张支付卡。API 按量付费、没有订阅费，但余额归零后请求就会失败。
用于发出第一个请求的 curl 或 Python 3.9+。
Apifox，如果你想把 Key 存为本地私密变量，并把请求保存成可重复执行的测试。

第 1 步：登录 API 控制台并创建项目

打开 console.perplexity.ai，选择一种登录方式。登录会创建 Perplexity 账号，但不会创建 API 项目。首次进入时，配置向导会要求你先创建或加入一个项目，然后才能生成 Key，因为 Key 是按项目隔离的。

在左侧边栏打开 Settings，填写组织名称、地址和税务信息，这些会出现在发票上。如果公司已经有项目，让管理员把你加进去，不要另建一个。不同项目有各自独立的余额和 Key，这对隔离生产应用和试验项目很有用。

第 2 步：添加支付方式并购买额度

打开 Billing 页面并添加银行卡。根据官方文档，添加支付方式不会立即扣款，只是保存信息供后续使用。然后购买额度。余额、按模型拆分的用量和发票历史都在这个页面上。

这里有两个细节要注意。API 从预付额度中扣费，余额用完后你的 Key 会被封禁，直到你充值。文档把这种失败描述为 401 而不是 402，所以额度耗尽的调用一眼看上去像是鉴权 bug。另外，在 Auto reload 旁边点击 Change preferences，可以让控制台在余额低于你设定的阈值时自动充值。生产环境上线前先把这项打开。

文档没有公布最低购买金额，以 Billing 页面显示为准。决定速率限制的用量档位取决于账号生命周期内累计购买的额度，而不是当前余额。

第 3 步：生成 API Key

在控制台打开 API Keys 页面并创建一个 Key。给它起一个有意义的名字，比如 dev-laptop 或 prod-search-worker。创建之后，名字是区分不同 Key 的唯一方式，因为完整值只显示一次，之后无法再获取。请立刻复制保存。

把 Key 放进环境变量，不要写进代码：

export PERPLEXITY_API_KEY="pplx-your-key-here"

在 Windows 上使用 setx PERPLEXITY_API_KEY "pplx-your-key-here"，然后打开一个新的终端。

一个项目里可以创建多个 Key，所以按环境和按服务各建一个。吊销 Key 是不可逆的，Key 泄露时这正是你想要的效果。如果不确定某个 Key 是否已经泄露到仓库里，先对 git 历史跑一遍密钥扫描工具，再做轮换。

第 4 步：发出第一个 Sonar 请求

当前接口是 POST https://api.perplexity.ai/v1/agent。鉴权使用标准的 bearer header，即 Authorization: Bearer $PERPLEXITY_API_KEY。body 接收一个 model 和一个 input 字符串。这个接口上 Sonar 的模型 id 是 perplexity/sonar，加上 web_search 工具会让它搜索实时网页并附上引用来源。

问它一个答案明确、但会随时间变化的问题：

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity/sonar",
    "input": "Which Node.js release line is currently Active LTS, and when does it reach end of life?",
    "tools": [{ "type": "web_search" }]
  }' | jq

响应里包含 output_text，即纯文本形式的答案，以及一个 output 数组，模型执行的每一步对应其中一项。message 项保存答案；search_results 项列出它读过的页面，每个页面带有 url、title、snippet 和 date。usage 对象报告 token 数量和费用。status 为 completed 表示本次运行已完成。

用官方 SDK 在 Python 中发出同样的请求：

pip install perplexityai

from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY from the environment

response = client.responses.create(
    model="perplexity/sonar",
    input="Which Node.js release line is currently Active LTS, and when does it reach end of life?",
    tools=[{"type": "web_search"}],
)

print(response.output_text)

如果你更习惯 OpenAI SDK，把 base_url="https://api.perplexity.ai/v1" 设好，并用相同的参数调用 client.responses.create()。SDK 会把它发到 /v1/responses，Perplexity 接受这个路径作为别名。预设（fast、low、medium、high、xhigh）会替你打包好模型、token 预算和工具；在 OpenAI SDK 中通过 extra_body 传入。

如果你还在用旧版 chat-completions 形式

老代码把 messages 发到 https://api.perplexity.ai/v1/sonar，模型 id 用 sonar、sonar-pro、sonar-reasoning-pro 或 sonar-deep-research，并读取 choices[0].message.content。这种形式可以用到 2026 年 9 月 27 日。迁移指南把 sonar 映射为 perplexity/sonar，把 sonar-pro 映射为带 low 预设的 perplexity/sonar，把 deep research 映射为 high 预设。search_domain_filter 和 search_recency_filter 选项移到了 web_search 工具内部，变成一个 filters 对象。

第 5 步：在 Apifox 中保存 Key 和请求

一次能跑通的 curl 不算测试。下面是我们在 Apifox 里的做法，让 Key 不上云，并且请求可以随时运行。

创建环境。新建一个名为 Perplexity 的环境，包含两个变量：base_url 设为 https://api.perplexity.ai，作为共享值；PERPLEXITY_API_KEY 的共享值留作占位符，真实 Key 只放在本地值里。本地值保存在客户端缓存中，不会同步给同事，这正是关键所在。我们那篇讲 Apifox 环境与密钥变量的文章更详细地说明了共享值和本地值的区别。

构建请求。新建请求，POST {{base_url}}/v1/agent。添加 header Authorization: Bearer {{PERPLEXITY_API_KEY}}，把 body 类型设为 JSON，并粘贴与上面 curl 相同的 body。选择 Perplexity 环境后点击发送。你应该能在响应面板中看到 output_text 和 search_results 块。

把它变成测试。添加三条断言：状态码为 200，$.status 等于 completed，以及 $.output_text 不为空。把请求保存进测试场景。现在团队里任何人都可以拉取项目，把自己的 Key 粘贴到本地值中，一键验证配置是否正确。轮换 Key 只需要改一个字段，不用在脚本里到处翻找。

速率限制与单次请求的成本

Agent API 的速率限制随用量档位提升，档位由账号累计购买的额度决定，参见速率限制页面：

档位	已购买额度	每秒请求数	每分钟请求数
0	$0	1	50
1	$50+	3	150
2	$250+	8	500
3	$500+	17	1,000
4	$1,000+	33	4,000
5	$5,000+	33	8,000

限流使用漏桶算法，因此不超过上限的短时突发可以放行。超限时 API 会返回 429 并带上 Retry-After header，被拒绝的请求不计费。当前档位显示在控制台 Pricing 页面的 usage tiers 标签下。

价格这里一段就够了。定价页面列出 Agent API 上 perplexity/sonar 的价格：每百万输入 token $0.25、每百万输出 token $2.50，另外每次 web_search 调用 $0.0025。旧版 Sonar chat-completions 模型计费方式不同：sonar 输入和输出均为每百万 token $1，另按搜索上下文大小每千次请求收取 $5 到 $12。完整的费用拆解以及 Pro 账号相关的内容，见我们的 Perplexity API 指南。

常见错误及解决办法

401 Unauthorized。按可能性从高到低有三个原因：header 写错了（必须是 Authorization: Bearer <key>，而且 shell 变量必须在同一个终端里 export 过）、Key 已被吊销，或者额度余额为零。在重新生成任何东西之前，先看 Billing 页面。Python SDK 对这种情况会抛出 AuthenticationError。

400 Bad Request。通常是旧格式的 body 发到了新接口：用了 messages 而不是 input，或者在 /v1/agent 上用了不带前缀的 sonar-pro 模型 id。SDK 会把这种情况暴露为 ValidationError。

404 Not Found。路径写错了。/v1/agent 是 Agent API，/v1/sonar 是旧版 chat-completions 接口；文档里没有列出其他路径。

429 Too Many Requests。你触发了当前档位的限制。读取 Retry-After，等待相应时长，然后用指数退避加抖动重试。如果需要持续吞吐量，购买额度可以提升档位。SDK 的错误处理指南给出了 RateLimitError 的用法示例。

500 或 503。服务端问题。延迟后重试；过于密集的重试循环会让限流更严重。

FAQ

Perplexity API Key 有免费的吗？

文档中没有免费档位。API 从预付余额按量付费，没有额度的项目会被封禁。用 perplexity/sonar 加一次网页搜索发出第一个请求，成本不到一分钱，所以少量充值就够做很多测试。

第一次请求应该用哪个模型 id？

在 /v1/agent 上使用 perplexity/sonar 并带上 web_search 工具。它是成本最低的联网检索方案，也是迁移指南把旧的 sonar 和 sonar-pro id 映射到的目标。当你希望由 Perplexity 自己选择模型和搜索预算时，可以改用 low 或 medium 这类预设。

如果只想要搜索结果，需要用 Agent API 吗？

不需要。独立的 Search API 会返回排序后的结果，但不运行模型，当你把页面喂进自己的流程时成本更低。我们那篇 Perplexity Search API 实践文章给出了请求结构和筛选参数。

如何在不中断服务的情况下轮换 Key？

在同一个项目里再创建一个 Key，把它部署到所有原先使用旧 Key 的地方，确认新 Key 上有流量后，再吊销旧 Key。吊销不可逆，所以要先把所有调用方都更新完。如果你想把轮换脚本化，Perplexity 还提供 /generate_auth_token 和 /revoke_auth_token 两个接口。

总结

登录、创建项目、购买额度、生成 Key、用 perplexity/sonar 向 /v1/agent 发一个请求，这就是完整流程。把 Key 存为 Apifox 中的本地值，并把请求保存为测试，团队里的下一个人几分钟内就能得到一套可验证的配置。如果你的代码还在用 chat-completions 接口，请在 2026 年 9 月 27 日之前完成迁移。