ZCloudAPI 提供一组面向不同客户端和模型能力的兼容 API。调用前先用当前 API Key 请求 /v1/models，最终以返回的模型名、协议能力和权限为准。

认证和地址

所有模型请求都需要携带 API Key。OpenAI-compatible 接口使用下面的公共格式：

Authorization: Bearer sk-你的-ZCloudAPI-Key

场景	Base URL	认证方式
OpenAI、Codex、Cursor、SDK	https://api.zcloudapi.com/v1	Authorization: Bearer ...
Anthropic SDK	https://api.zcloudapi.com	x-api-key: ...
Claude Code	https://api.zcloudapi.com	由客户端拼接 /v1/messages

官网与控制台地址 https://console.zcloudapi.com 只用于注册、创建 Key、充值和查看日志，不要填入模型客户端。

常用接口地图

方法	路径	用途	返回或协议
GET	/v1/models	查询当前 Key 可见模型	JSON 模型列表
GET	/v1/models/:model	查询单个模型元数据	JSON 模型详情
POST	/v1/completions	兼容旧版 Text Completions 客户端	JSON 或 SSE
POST	/v1/chat/completions	普通对话和 OpenAI-compatible 客户端	JSON 或 SSE
POST	/v1/responses	Codex、Agent、工具调用	Responses JSON 或 SSE
POST	/v1/responses/compact	需要显式压缩语义的 Responses 客户端	Responses JSON 或 SSE
POST	/v1/messages	Anthropic Claude Messages 协议	Messages JSON 或 SSE
POST	/v1/images/generations	图片生成	签名 URL 或 Base64
POST	/v1/images/edits	使用输入图片进行编辑	签名 URL 或 Base64
POST	/v1/videos	提交视频生成任务	JSON 任务 ID
GET	/v1/videos/{id}	查询视频生成及转存状态	JSON 状态与签名 URL
GET	/v1/videos/{id}/content	鉴权下载已转存的视频	302 跳转至 OSS
POST	/v1/embeddings	文本向量化	JSON 向量数组
POST	/v1/rerank	文档重排序	JSON 排序结果
POST	/v1/audio/transcriptions	音频转文字	JSON 或文本
POST	/v1/audio/translations	音频翻译	JSON 或文本
POST	/v1/audio/speech	文本转语音	二进制音频
POST	/v1/moderations	内容安全分类	JSON 分类结果
GET (WebSocket)	/v1/realtime	低延迟实时音频客户端	WebSocket 事件流

图片新接入统一使用 /v1/images/generations 和 /v1/images/edits。Gemini 原生客户端仍可使用 /v1beta/models/{model}:{action}，但它属于兼容路径；统一 Images API 的返回结构更稳定。

视频新接入使用 /v1/videos，兼容提交入口为 /v1/video/generations。视频先返回任务 ID，再查询进度、等待 OSS 转存并下载，不使用文本 SSE。完整参数和可运行示例见「视频生成」。

并非每个上游渠道都支持所有接口。即使路径存在，当前 Key 也可能因为模型权限、用户分组或渠道能力而返回错误；不要把“路由存在”当作“模型一定可用”。

先确认模型和协议

curl "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

使用 data[].id 中的完整模型名。模型列表是经过 Key、用户分组和渠道过滤后的结果，比模型广场或第三方文章中的示例更可靠。

如果需要知道一个模型适合哪个接口，可以先按用途判断：

• 普通问答、兼容桌面客户端：优先尝试 Chat Completions。
• Codex、Agent、工具调用：优先尝试 Responses API。
• Claude 原生 SDK：使用 Messages API。
• 向量搜索：使用 Embeddings；文档检索排序：使用 Rerank。
• 图片、音频和审核：使用对应的专用接口，并确认模型列表中存在匹配能力。

流式和返回格式

• Chat Completions、Responses、Messages 在模型支持时可以设置 "stream": true，响应会以 SSE 事件逐步返回。
• 第一次接入或排障时先使用 "stream": false，确认状态码、正文和 usage 后再启用流式。
• 图片接口设置 response_format=url 时返回临时签名地址，设置 response_format=b64_json 时返回内联 Base64；图片编辑接口需把该参数作为 multipart 字段提交。
• 视频接口返回异步任务，不传 stream 或图片的 response_format；等 status=completed 且 metadata.storage.status=ready 后再下载。
• 音频语音接口成功时返回二进制内容，不要按 JSON 解析；请根据 Content-Type 直接写入文件或交给音频播放器。

最小请求示例

curl -i "https://api.zcloudapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 复制的模型名",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16,
    "stream": false
  }'

成功后再按协议阅读「Chat Completions」「Responses API」或「Claude Messages」。

错误处理建议

状态码	常见原因	建议
400	参数、协议或模型能力不匹配	退回最小请求，逐项加回可选字段
401	Key 无效或认证 Header 错误	重新复制 Key，检查当前终端变量
403	用户分组或 Key 权限不足	检查 Key 限制和 /v1/models 结果
404	地址层级错误或接口不存在	检查是否重复或遗漏 /v1
429	频率、并发或上游限流	降低并发并使用有限指数退避
5xx	网关或上游临时异常	记录时间、模型和日志，有限重试

不要对所有错误盲目重试：400、401 和 403 通常需要修改请求或权限；持续的 429 也需要降低请求速率。

SDK 和安全

Python、Node.js 以及 Codex、Claude Code、Cursor 的完整配置见对应章节。生产环境建议：

• 为开发、测试和生产分别创建 Key，按最小权限配置模型和额度。
• 使用环境变量或 Secret 管理器注入 Key，不要写进源码、前端代码、截图或公开日志。
• 不要把完整请求 Header、音频二进制或图片 Base64 写入普通日志。
• 在控制台「使用日志」核对请求、模型、Token 和扣费；这也是判断是否连到了正确 Base URL 的最快方法。