本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。
快速判断：我应该看哪一段？
- 只想聊天：先看桌面端的基础配置。
- 要接入 MCP、知识库或工作流：看 Agent/自动化章节。
- 要在终端写代码：看 CLI、Provider 和环境变量章节。
- 遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。
Coze 工作流：从输入到获取 URL（融合自原文档）
如果你是扣子vip,可以直接下载工作流导入即可
https://wwaod.lanzn.com/b011lwl8ij
密码:3qnp
以sora2为例子从输入文本和上传图片到最后获取url的简单循环工作流（下面是整体图）
一、开始
根据提示词和图片 新增输入的变量，根据接口需要的参数来，需要输入更多参数也可以添加
二、请求模型 （新增http节点）
根据文档配置http请求
1.第一个红框位置配置请求方式和url
2.第二个红框配置请求头
3.第三个地方配置请求体，请根据文档中相应的请求体选择格式，在这个例子中用的json，其中标有开始的是从前面的输入中获取的参数，在编辑直接{}输入就能选择
三、处理请求结果获取taskId（新增代码节点）
如图所示在输入的时候变量值直接获取上一个的输出body
使用代码解析body获取其中的id（在本示例中代码选择的是JavaScript 代码如下）
async function main({ params }: Args): Promise<Output> {
// 1. 从 params.input 中获取 body 字符串
// 注意：这里假设 params.input 是整个 HTTP 响应对象
const bodyStr = params.input;
// 2. 将字符串格式的 body 解析为 JSON 对象
// 因为 body 的值是一个字符串 "{\"id\":...}"，所以需要 JSON.parse
let taskId = "";
try {
const bodyObj = JSON.parse(bodyStr);
taskId = bodyObj.id;
} catch (e) {
// 防止解析失败导致运行报错
console.log("JSON 解析失败:", e);
}
// 3. 构建输出对象，返回 taskId
const ret = {
"taskId": taskId
};
return ret;
}最后输出的位置的变量名请与代码中ret 中的参数名一致
四、循环请求查询接口获取url（新增循环节点）
1\. 设置循环（在本次示例中使用的是无限循环根据判断条件跳出循环）根据需要设置
中间变量是获取的前一个代码节点输出的taskId
输出了url和状态
2\. 在循环中新增一个http节点请求查询任务
其中参数请求体根据文档中的使用的模型的查询任务来
3\. 新增一个代码节点获取url和任务状态
如图所示 输入获取的是查询任务的输出body代码如下
async function main({ params }: Args): Promise<Output> {
// 1. 从 params.input 中获取 body 字符串
const bodyStr = params.input;
// 2. 将字符串格式的 body 解析为 JSON 对象
let url = "";
let status = "";
try {
const bodyObj = JSON.parse(bodyStr);
url = bodyObj.video_url;
status = bodyObj.status;
} catch (e) {
// 防止解析失败导致运行报错
console.log("JSON 解析失败:", e);
}
// 3. 构建输出对象，返回 taskId
const ret = {
"url": url,
"status": status
};
return ret;
}4.新增一个判断节点来判断查询是否获取了url
在这个示例中，判断节点设置了两个分支第一个分支是获取的上一个代码节点输出的url判断是否为空
第二个分支是判断状态是否为失败
5根据判断的结果来执行
新增终止循环的节点，当判断节点的第一个判断成功或者第二个判断成功时都终止循环
新增定时器节点和继续循环节点，当判断节点的两个判断都为否时先执行定时器（防止请求并发数量导致请求失败，建议设置为1500ms），定时器后连接继续循环
五、处理循环得到的结果（新增一个代码节点）
因为循环后获得的结果是一个数组需要处理只获取最后输出的结果（代码如下）
输入的是循环输出的结果
async function main({ params }: Args): Promise<Output> {
// 获取输入
const urls = params.urls;
const statuss = params.statuss;
// 3. 构建输出对象，返回 taskId
const ret = {
"url": urls[urls?.length -1],
"status": statuss[statuss?.length -1]
};
return ret;
}输出的是处理后的url和状态
六、判断url是否有值来确定视频生成成功还是失败
七、最后输出结果
如图所示输出成功和失败的结果然后结束，可以根据自己的需要把输出文本还是变量，也可以把输出结果放在结束节点输出
#
八、实现效果
接入检查
- API Key 使用
$QINGYUN_TOP_API_KEY占位符保存，不要直接粘贴到公开代码或截图。 - OpenAI 兼容客户端通常使用
https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写/v1。 - 先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。
Coze 工作流使用中转 API（融合自原文档）
1.创建一个新的项目
2.建立一个新的工作流
3.添加http请求
4.填写内容
url填https://top.qingyuntop.ai/v1/chat/completions
填写key
5.点击试运行，成功
接入检查
- API Key 使用
$QINGYUN_TOP_API_KEY占位符保存，不要直接粘贴到公开代码或截图。 - OpenAI 兼容客户端通常使用
https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写/v1。 - 先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。
统一接入检查与故障排查
- 401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
- 404：核对应用要求的 Base URL 形式；
https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1和完整路径不能重复拼接。 - 模型为空或不可用：调用
GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。 - 切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
- 生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。
> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。
发布前检查
以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。
- 模型 ID：先用目标 API Key 请求
GET https://top.qingyuntop.ai/v1/models，把返回的data[].id原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。 - 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从
output读取，Chat 的返回从choices[].message读取。 - Base URL：通常填写
https://top.qingyuntop.ai/v1，也就是只保留一个/v1。要求完整接口地址的客户端才追加/responses或/chat/completions，不要重复追加。 - 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
- 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录
request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。