选择调用协议
青云TOP API 为三类聊天协议提供统一的本站 API Key 鉴权。输入媒体和工具的结构由协议决定；模型名称相同，也不要混用字段。
| 协议 | 本站入口 | 适用场景 |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | OpenAI 聊天，以及 Claude / Gemini 的通用聊天兼容 |
| Claude Messages | POST /v1/messages | Claude 文本、PDF、工具、思考与原生内容块 |
| Gemini 原生 | POST /v1beta/models/{model}:generateContent | Gemini 多模态、搜索、代码执行与完整思考签名 |
需要音频转写、TTS、向量嵌入时使用各自专用动作，不能把所有内容塞入聊天接口。生成图片或视频请进入对应模型目录。
模型与下一步
- OpenAI 模型与参数选择：GPT‑6 Astra、GPT‑5.6 系列及专用音频、向量模型。
- Claude 模型与协议选择：Fable 5.1、Opus 5、Sonnet 5、Haiku 4.5。
- Gemini 模型与协议选择：3.8 Flash、3.1 Pro、3.5 Flash-Lite 与专用 TTS / Embedding。
截至 2026-10-02，本站公开 pricing 目录包含 443 个型号，其中 378 个被目录标记为可用于通用聊天候选；这只是公开目录快照，不等于某个 API Key 的可见模型。当前生产服务为 v1.0.0-rc.40。上游适配层后续版本已修复 Claude 自动思考、逐消息 output_config 和 Responses→Chat 工具转换，待生产服务升级后再作为本站已部署行为；本页只承诺生产版本已经核对的入口。
先用 GET /v1/models 查询当前 Key 可见的模型，再按动作选参数。模型目录、账号权限与实时可用性是三个层面；列表中存在型号不保证所有工具组合或上游容量可用。
鉴权与基础地址
使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY。替换占位符，保留 Bearer 后的空格。无需厂商 API Key。
所有请求发往 https://top.qingyuntop.ai。不要把文档站地址作为 API 地址。使用 OpenAI SDK 时 base_url 通常写为 https://top.qingyuntop.ai/v1；原始 HTTP 示例已包含完整路径，不要再次追加 /v1。
对话、流式与用量
Chat / Messages / generateContent 每轮发送所需历史；这些接口不提供聊天任务的创建、轮询或断点续传。需保存 response ID 用于日志，保存完整内容用于多轮。工具调用返回的是执行建议，你的应用还需完成校验、执行和结果回传。
流式连接按 SSE 事件读取，不能把一次网络读取当作完整 JSON。模型可能返回截断、拒绝、工具请求或空候选；HTTP 200 本身不代表得到了完整答案。用量字段以实际协议返回为准，价格和额度查看控制台。
常见错误
401：检查本站 API Key 和 Bearer 格式；403：确认此 Key 可用该模型；429：遵循 Retry-After 退避。超时或 5xx 时保留请求标识和脱敏错误，避免盲目重发。
413：缩小文件并检查 Base64 后的完整请求体；415：核对 JSON 与 multipart；流中 error：停止拼接正文并保留错误；结构化 JSON 解析失败：先检查是否截断或拒绝。
能力边界
本目录不提供厂商 Files 上传、Messages count_tokens、Gemini countTokens、厂商 Batch 或 Interactions 的接入教程。不要将厂商地址直接换成本站域名后调用这些入口。Responses 使用独立的 Responses 文档。
参考：OpenAI 公共 API 规范、Claude Messages、Google 官方 generateContent 示例。