按需求找到调用文档
先看你希望应用完成什么，再选择模型系列。下表是文档导航；各系列开放的动作、型号和限制，以链接中的支持范围为准。
| 你的需求 | 从这里开始 | 重点确认 |
|---|---|---|
| 对话、写作、代码、看图问答 | Chat 调用、Responses 调用 | 模型是否支持对应输入、工具调用和流式输出 |
| 生成或编辑图片 | GPT Image、Gemini Image、Grok Image、豆包生图、千问生图支持说明 | 生成与编辑的区别、图片数量、尺寸及输入格式 |
| 生成视频 | Sora、Veo、豆包视频、通义万象 | 文生或图生、时长、分辨率、查询与下载 |
| 视频参考图、首尾帧等动作 | 可灵、海螺、Vidu | 每个动作适用的模型、素材要求和协议 |
| 生成音乐或歌词 | Suno 接入概览 | 音乐与歌词的请求区别、任务 ID、结果文件 |
| 语音合成、音频转文字 | 语音合成、音频转文字 | 返回音频还是文字、上传方式、语言与音色 |
| 向量检索、结果重排序 | Embeddings、Rerank | 嵌入模型和重排序模型用途不同，分别使用对应接口 |
| MJ 或聚合平台中的模型 | Midjourney、Replicate、Fal-ai | 平台专属请求格式、任务状态及结果字段 |
已确定厂商或模型名称时，可直接展开左侧目录，或使用顶部搜索。标题标为“支持说明”“接入状态”“官方参数参考”的页面，请先阅读开头的限制，再决定调用方案。
接入前准备三项信息
1. 青云TOP API Key
在控制台创建用于应用调用的 API Key，并确认账户余额、密钥额度、有效期及所选分组。操作说明见创建 API Key和模型分组说明。
普通模型请求使用以下请求头，将 YOUR_API_KEY 替换为你的本站 API Key，保留 Bearer 后的一个空格。不同公开鉴权格式以具体接口页面为准。
Authorization: Bearer YOUR_API_KEY本站调用使用本站 API Key。请在服务端妥善保存生产密钥，避免把它公开在网页源码、代码仓库或错误日志中。
2. API 地址
| 配置位置 | 应填写什么 |
|---|---|
| HTTP 请求的基础地址 | https://top.qingyuntop.ai，再追加接口页面给出的完整路径 |
| OpenAI SDK 的 Base URL | 通常为 https://top.qingyuntop.ai/v1，由 SDK 追加资源路径 |
| 其他 SDK 或客户端 | 按其接入教程确认是否自动追加 /v1 或具体接口路径 |
例如模型列表的完整地址是 https://top.qingyuntop.ai/v1/models。文档站地址不用于模型调用；也不要把 /v1 重复拼接成 /v1/v1/...。详见 Base URL 说明。
3. 模型 ID 与适用能力
在模型广场查看型号、分组和价格，再通过下文的模型列表请求核对当前 API Key 返回的完整 data[].id。发送请求时保留模型 ID 的完整拼写，不自行删去前缀或版本后缀。
型号名称、调用协议和可用动作是三件事。模型列表中出现某个 ID，不代表它接受全部接口、全部参数，或保证每次上游调用成功。最终选择需同时满足对应教程的模型限制和你的账号权限；价格以本站当前价格页面及实际用量为准。
选择与模型匹配的协议
| 调用格式 | 典型入口 | 怎样选择 |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | 已有应用使用 messages 和 choices 时，确认目标模型支持这一格式 |
| Responses | POST /v1/responses | 应用使用 input 和 output 时，查看目标模型对工具、流式、后台等模式的具体支持 |
| Images | POST /v1/images/generations 或 POST /v1/images/edits | 区分生成与编辑；按模型教程选择 JSON 或文件上传方式 |
| 统一视频或任务格式 | 以对应视频、音乐教程为准 | 创建后按同一协议查询，保存创建返回的公开任务 ID |
| 厂商原生或平台专属格式 | 以对应目录给出的本站路径为准 | 请求结构、额外请求头和结果字段按该格式填写 |
先确认模型和动作支持，再选客户端能处理的协议。 不要因为接口名相同，就认为不同型号支持相同功能；也不要把厂商官方示例仅替换域名后直接使用。
如果你正在迁移现有聊天应用，先保持它目前使用的 Chat 或 Responses 格式，跑通最小请求后再添加工具、多模态输入等能力。两种格式的请求和返回不能混用。
第一次请求：获取模型列表
这个请求用于检查地址、鉴权和模型列表访问，不提交生成任务，也不证明某个模型已完成生成测试。
方法与地址： GET https://top.qingyuntop.ai/v1/models。只需鉴权请求头，不需要请求体。
cURL 示例使用 Bash/Zsh 的换行写法，要求 cURL 7.76 或以上；Python 需要安装 requests；Node.js 示例适用于 20 或以上版本，保存为 .mjs 后运行。三种示例执行相同请求，替换 YOUR_API_KEY 即可。
curl --fail-with-body --connect-timeout 30 --max-time 120 "https://top.qingyuntop.ai/v1/models" \
-H "Authorization: Bearer YOUR_API_KEY"确认 HTTP 状态正常且响应未返回 success: false 后，在 JSON 的 data 数组中读取每项 id。若返回 success: false，先按 message 排查，不要将它视为模型列表成功返回。从中选择与你需要的能力相匹配、且对应教程支持的模型；不要直接选列表中的第一个型号。若没有所需模型，先核对密钥的分组和模型限制，必要时联系本站支持。
接下来完成一次模型调用
- 打开对应教程。 从上方导航表或左侧目录找到模型的概览，确认输入素材、动作和调用格式。
- 按参数说明填写。 使用教程给出的 HTTP 方法、完整本站 URL 和最小请求体，替换 API Key、模型 ID 及需要上传的素材。
- 先跑通一种场景。 先验证基础文本、单图或短视频等目标动作，再增加工具、参考素材和流式等可选能力。
- 按结果继续处理。 同步读取正文；流式消费事件；异步保存任务 ID 并查询、下载。仅收到创建成功响应时，先显示“处理中”。
发送 JSON 时设置 Content-Type: application/json；上传文件时按教程使用 multipart，让客户端生成 boundary，不要继续设置 JSON 的 Content-Type。通用 SDK 不一定覆盖每个专属接口，可直接参考对应页面的 HTTP 示例。
正确处理返回结果
| 返回方式 | 应如何处理 |
|---|---|
| Chat 同步响应 | 从 choices 读取消息并检查完成原因；工具调用可能没有普通文本正文 |
| Responses 响应 | 按 output 中的项目类型读取内容，并检查状态和错误；不要使用 Chat 的 choices 解析方式 |
| SSE 流式响应 | 按完整事件边界解析增量和结束事件；一次网络读取可能只包含半个事件，也可能包含多个事件 |
| 异步任务 | 保存创建返回的公开 ID，使用同一教程的查询接口，确认成功终态后再读取产物或下载 |
HTTP 成功不等于生成完成。各平台的状态名称、错误字段、任务 ID 和下载方式可能不同，不能套用同一套固定字段。模型文档若要求分别保存 Responses ID 和任务 ID，应分别保存并用于对应接口。
为请求设置超时，为查询设置间隔、退避和业务等待上限。断线或客户端等待超时不自动代表生成失败或取消；已有任务 ID 时先查询状态，避免盲目重复创建。完成后及时保存需要保留的文件，临时下载链接不适合作为永久存储地址。
遇到问题时从这里排查
| 现象 | 先检查什么 |
|---|---|
| 401 或鉴权失败 | API Key 是否完整、有效；是否使用了本站密钥及正确请求头 |
| 403、模型不可用或无权限 | 密钥和账号的分组、模型限制，以及对应教程是否支持目标动作 |
| 404 或返回 HTML 网页 | 是否用了文档域名、错误路径、重复 /v1，或未经本站文档确认的厂商路径 |
| 400 或参数错误 | 字段位置与类型、必填项、素材格式，以及型号对应的尺寸、时长和数量组合 |
| 429 或暂时不可用 | 阅读错误正文，降低并发并采用有限退避；不要无限重试 |
| 有响应却读不到内容 | 是否混用了 choices、output、任务状态或平台专属返回字段 |
| 创建后长时间未完成 | 保存任务 ID 并查询；先确定已有任务状态，再决定是否重新提交 |
| 结果已完成但无法下载 | 检查结果链接是否过期、是否需要鉴权，以及该任务的下载说明 |
继续阅读错误处理、限流与超时和模型定价说明。需要联系本站支持时，请提供调用时间、模型 ID、接口路径、HTTP 状态、脱敏错误和任务 ID；不要发送完整 API Key。