Perplexity API Skill
Perplexity 现在有五套并行 API——新的 Agent API 是官方推荐的默认入口，而被文档标注为过时、但仍完全可用的 Sonar Chat Completions 才是大多数人训练记忆里"Perplexity API"的样子。最容易踩的坑：Agent API 裸传 model 不带 tools 时默认不联网、没有引用，和 Sonar"传 model 就自动搜索"的行为完全相反；域名/时间过滤字段在三套 API 里同名，但挂载位置各不相同。
Authorization: Bearer $PERPLEXITY_API_KEY，五套 API 通用，Key 需先建 Project 才能生成Agent 工具更新 2026-09-21安装
选你用的 Agent，复制命令。
npx -y skills add fxp/skillify --skill perplexity --agent claude-code --yes装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。
npx -y skills add fxp/skillify --skill perplexity --agent codex --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill perplexity --agent cursor --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill perplexity --agent opencode --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill perplexity --agent gemini-cli --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill perplexity --agent github-copilot --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill perplexity --agent trae --yes装到项目的 .trae/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill perplexity --agent windsurf --yes装到项目的 .windsurf/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill perplexity --agent qwen-code --yes把 --agent 换成你用的 Agent 标识，可以一次写多个。skills CLI 1.5.25 共支持 79 个，例如 qwen-code、kimi-code-cli、trae-cn、qoder、lingma、cline、roo。
或者让 Agent 自己装
读 https://github.com/fxp/skillify/blob/main/skills/perplexity/prompt.md 并照它执行装对了的标志：references/ 下有 6 份文档。
装好后，可以这样问你的 Agent
这份 Skill 覆盖的典型任务。点一下复制。
6 类能力
每类能力对应一份 reference，Agent 按任务只打开需要的那份。
Sonar 经典问答
OpenAI 兼容 messages/choices 结构拿带引用问答、流式、结构化输出、媒体附件、异步版本——官方标注过时但仍可用
Agent API
多提供商模型、preset 起步 vs 显式 model+tools、内置 web_search 等工具、类型化流式事件、结构化输出、后台长任务
Search API
只拿排名网页结果、不经过 LLM，多查询请求、人物搜索、计费按请求数与限流按 query 单位的差异
搜索范围控制
域名/时间/语言/地理位置过滤字段在 Sonar / Agent API / Search API 三处同名但挂载位置不同的对照表
模型选型
Sonar 四个模型 vs Agent API 多提供商模型目录、preset 速查表、sonar-deep-research 的额外计费结构
错误、限流与定价
SDK 分类异常、按 usage tier 分级的限流表、五套 API 各自完全不同的计费形状、Embeddings API
当前事实
整理自官方文档（抓取于 2026-09-21），还没有用真实凭证验证。
| 项 | 值 |
|---|---|
| Base URL 因 API 而异 | Sonar /v1/sonar、Agent /v1/agent（别名 /v1/responses）、Search /search（没有 /v1 前缀）、Router /router/v1、Embeddings /v1/embeddings |
| Agent API 默认不联网 | 裸 model 不带 tools = 纯聊天，要联网必须显式传 tools: [{"type": "web_search"}]，或者用自带工具的 preset |
| 模型枚举 | Sonar 只有 sonar/sonar-pro/sonar-reasoning-pro/sonar-deep-research 四个，没有单独的 sonar-reasoning |
| Search API 计费与限流不是一回事 | 一次带 5 条 query 的请求，计费按 1 次请求算（$5/1000 次），限流按 5 个 query unit 算（50 units/秒） |
| 结构化输出 name 字段 | Sonar 的 json_schema.name 可选（默认 "schema"）；Agent API 的同名字段必填（1–64 个字母数字字符） |
照通用经验写容易错的 7 件事
来自官方文档，还没有用真实凭证验证。
- Agent API 默认不联网、不引用。这是从"Sonar 系列天生自带搜索"心智迁移过来最容易踩的坑——裸
model+ 无tools就是一次纯聊天补全。 - 行内引用标记
[1][2]不是自动加的。即使挂了web_search工具，模型是否插入方括号标记取决于提示词；无论有没有标记，都应以search_results[].id/url为准，不要靠正文里有没有方括号判断可信度。 - 流式响应里搜索结果只在最后一个（或几个）chunk 出现，不是逐步到达。按"内容分片一样逐步渲染引用列表"的假设去做 UI，会长时间看到空列表。
- Agent API 里 Anthropic 模型必须显式传
max_output_tokens，否则 400。这是该模型族特有的强制要求，OpenAI/Google/xAI 等其他模型不强制。 - 域名过滤的 allowlist/denylist 不能混用。
search_domain_filter数组里的条目要么全部不带-前缀，要么全部带，最多 20 条；日期一律MM/DD/YYYY，不是 ISO 8601 的YYYY-MM-DD。 search_recency_filter（相对时间窗）不能和精确日期过滤器同时使用。想同时要"精确范围"和"相对窗口"是不支持的组合。- Embeddings 向量未归一化。
base64_int8编码必须用余弦相似度比较，base64_binary编码必须用汉明距离——套用"归一化向量随便用内积"的直觉会得到错误的相似度排序。