应核对官方API动态获取的Model ID，使用model-versions端点验证版本，启用redirect_model_aliases参数支持别名重定向，并通过Pro设置页白名单强制校验模型名称一致性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在调用Perplexity API时收到模型名称错误（如“model not found”、“invalid model ID”或HTTP 400响应），通常是由于请求中使用的模型标识符与后端当前支持的Model ID不匹配所致。Perplexity后端模型命名体系已更新，旧版名称（如pplx-7b-online）可能已被弃用或重映射为新版ID（如sonar-small-online）。以下是解决此问题的具体操作步骤：
一、核对官方最新Model ID列表
Perplexity官方不再维护静态模型名称表，所有有效Model ID均通过其公开API元数据端点动态提供。该方式可确保获取实时、未经缓存的模型标识符集合，避免依赖过期文档。
1、在终端中执行cURL命令，向Perplexity模型发现端点发起GET请求：
curl -H "Authorization: Bearer sk-prod-xxx" https://api.perplexity.ai/models
2、检查响应体中每个对象的id字段，例如"sonar-medium-online"、"claude-3-5-sonnet"、"gpt-4o-mini"等，这些即为当前可用的合法Model ID。
3、将响应中返回的id值与您代码中硬编码的model参数逐字比对，必须完全一致，包括大小写与连字符位置。
二、使用Model ID自动解析服务端版本映射
Perplexity提供专用端点用于查询某一Model ID所绑定的实际后端推理服务版本，该版本号直接反映模型部署的底层镜像哈希与上线时间戳，可用于精准定位兼容性问题。
1、构造请求URL：https://api.perplexity.ai/model-versions?model_id=sonar-medium-online（将sonar-medium-online替换为您实际使用的ID）
2、在请求头中添加Authorization: Bearer sk-prod-xxx，确保使用具备Pro权限的有效密钥。
3、解析返回JSON中的version字段，例如"v2026.03.28-1429-3a7f8c1"，该字符串表明该Model ID当前路由至2026年3月28日发布的第1429次构建版本。
4、若您的应用日志中记录了失败请求对应的version值，而该值未出现在最近三次返回结果中，说明该版本已被强制下线，需立即切换至新version对应的新Model ID。
三、启用模型别名自动重定向功能
Perplexity API网关支持模型别名机制，允许客户端继续使用历史名称（如pplx-7b-chat），由服务端自动将其307临时重定向至当前主推的等效Model ID。该机制需显式启用，且仅对部分旧名称生效。
1、修改原始POST请求URL，在末尾追加查询参数?redirect_model_aliases=true，例如：
https://api.perplexity.ai/chat/completions?redirect_model_aliases=true
2、保持原有请求体不变，仍使用旧模型名："model": "pplx-7b-chat"
3、发送请求后检查HTTP响应头中的X-Redirected-Model-ID字段，其值即为服务端实际分发的目标Model ID。
4、若响应状态码为307且Header中存在该字段，则说明重定向成功；若返回400且无此Header，表明该别名已彻底废弃，不可恢复。
四、通过Pro设置页同步模型命名空间
当账户启用Perplexity Pro订阅后，可在设置页激活“Strict Model ID Enforcement”开关，该功能会强制API网关拒绝所有未在账户白名单中注册的Model ID，从而提前暴露命名不一致问题，而非静默降级。
1、登录Perplexity Pro控制台，进入Settings → Pro Settings → Model Governance
2、找到“Model ID Whitelist Mode”选项，将其切换为Enabled
3、在下方输入框中粘贴您代码中实际使用的全部Model ID，每行一个，例如：
sonar-small-online
claude-3-5-haiku
gpt-4o-mini
4、点击Save Changes后，所有未列入白名单的model参数将立即触发HTTP 403响应，并附带详细错误信息：{"error": "model_id_not_whitelisted", "expected": ["sonar-small-online", "claude-3-5-haiku"]}
