本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。

快速判断：我应该看哪一段？

  • 只想聊天：先看桌面端的基础配置。
  • 要接入 MCP、知识库或工作流：看 Agent/自动化章节。
  • 要在终端写代码：看 CLI、Provider 和环境变量章节。
  • 遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。

第三方客户端接入（融合自原文档）

第三方客户端的界面不同，但配置逻辑相同：创建专用令牌，选择兼容协议，填写 青云TOP API 地址，再选择当前令牌可见的模型。

桌面与扩展

Agent 与命令行应用

协议转换

统一接入检查与故障排查

  1. 401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
  2. 404：核对应用要求的 Base URL 形式；https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1 和完整路径不能重复拼接。
  3. 模型为空或不可用：调用 GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。
  4. 切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
  5. 生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。

> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。