概览
云枢 API 是一个统一的国产大模型网关。你把请求发到本网关,网关按模型路由到对应上游(DeepSeek / 智谱 / 月之暗面 / 通义 / 豆包 / MiniMax 等),并把响应(含 SSE 流)实时回传。
| 项目 | 值 |
|---|---|
| 基础地址 | https://yunshuapi.yunshuhulian.cn/v1 |
| 协议 | OpenAI Chat Completions(兼 Anthropic Messages) |
| 鉴权 | Authorization: Bearer sk-ys-xxxx |
| 流式 | stream: true |
| 计费单位 | 人民币 / 每百万 token(图像按次) |
鉴权方式
所有接口都需要携带密钥,推荐放在请求头:
Authorization: Bearer sk-ys-你的密钥
同时兼容以下写法,方便不同客户端:
- x-api-key: sk-ys-xxx(Anthropic 风格)
- ?key=sk-ys-xxx(URL 参数,仅调试用)
快速开始
三步跑通:
curl https://yunshuapi.yunshuhulian.cn/v1/chat/completions \
-H "Authorization: Bearer sk-ys-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"messages": [{"role": "user", "content": "你好"}]
}'
对话补全
POST /v1/chat/completions,与 OpenAI 官方一致。
| 参数 | 类型 | 说明 |
|---|---|---|
| model | string | 必填,站内模型名,如 glm-5.3 |
| messages | array | 必填,role/content 结构 |
| stream | bool | 是否流式,默认 false |
| temperature | float | 采样温度 |
| max_tokens | int | 最大输出 token |
| top_p / stop / presence_penalty | — | 原样透传上游 |
响应透传上游结构,额外在响应头返回:X-Relay-Request-Id、X-Relay-Upstream、X-Relay-Model,便于排障。
流式输出
设置 "stream": true 后返回 text/event-stream,网关逐块转发,不做整段缓冲。
from openai import OpenAI
client = OpenAI(base_url="https://yunshuapi.yunshuhulian.cn/v1", api_key="sk-ys-你的密钥")
stream = client.chat.completions.create(
model="kimi-k3",
messages=[{"role": "user", "content": "写一段产品介绍"}],
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="", flush=True)
模型列表
GET /v1/models 返回当前密钥可用模型及价格。
{
"object": "list",
"data": [
{
"id": "deepseek-v4-pro",
"object": "model",
"owned_by": "yunshu",
"type": "chat",
"pricing": {"input": 2.2, "output": 6.5, "unit": "CNY/1M tokens"}
}
]
}
图像生成
POST /v1/images/generations,按次计费(¥/张),模型如 doubao-seedream-5.0-pro、kling-3.0。
curl https://yunshuapi.yunshuhulian.cn/v1/images/generations \
-H "Authorization: Bearer sk-ys-你的密钥" \
-H "Content-Type: application/json" \
-d '{"model":"doubao-seedream-5.0-pro","prompt":"赛博朋克风格的城市夜景","size":"1024x1024"}'
Anthropic 兼容
除 OpenAI 协议外,网关同时提供 POST /v1/messages,可直接给 Claude 风格客户端或 SDK 使用,鉴权支持 Authorization 与 x-api-key。
计费与额度
- 按 输入 token × 输入单价 + 输出 token × 输出单价 计费,单位 ¥/1M tokens;
- 图像类模型按 次 计费;向量模型只计输入;
- 余额在每次请求完成后扣除,可在控制台逐条核对明细;
- 支持日额度上限、Key 有效期、无限额度卡;
- 余额不足返回 401 insufficient_balance,不会产生欠费调用。
成本与售价双轨记录:后台可查看每个模型的成本、售价与毛利,方便定价。
限流与错误码
| HTTP | code | 含义 |
|---|---|---|
| 400 | invalid_json / missing_model | 请求体不合法或缺 model |
| 401 | invalid_key | 密钥不存在 |
| 401 | key_disabled / key_expired | 密钥被禁用或过期 |
| 401 | insufficient_balance | 余额不足 |
| 403 | model_forbidden | 该密钥无权调用此模型 |
| 404 | model_not_found | 模型未开放 |
| 429 | rate_limited / concurrency_limited | 触发 RPM 或并发限制 |
| 502 | upstream_error | 全部上游不可用(已自动重试与切换) |
| 503 | upstream_not_configured | 该模型未绑定上游 |
错误体统一为:{"error":{"code":"...","message":"...","type":"yunshu_relay_error"}}。
客户端接入
| 客户端 | 配置项 |
|---|---|
| Cherry Studio / Chatbox / NextChat / LobeChat | API 地址填 https://yunshuapi.yunshuhulian.cn/v1,密钥填 sk-ys-xxx,模型手填或从列表拉取 |
| LangChain | ChatOpenAI(base_url=".../v1", api_key="sk-ys-xxx") |
| Cursor / Continue / Cline | 选 OpenAI Compatible,Base URL 同上 |
| 自建后端 | 任意 HTTP 客户端,注意流式请求需关闭代理缓冲 |
常见问题
为什么返回「待接入」?
该模型尚未在后台绑定上游,或上游地址/密钥为空。管理员配置后自动可用。
同一个模型名,为什么有时快有时慢?
网关会在多条上游之间按权重分流并做健康检测;某条上游在晚高峰拥塞时会被降权,延迟会有波动。
能给我固定出口 IP 吗?
可以,网关部署在固定公网 IP 的业务机上,需要白名单可联系管理员。
是否支持发票 / 对公?
支持,具体开票信息与代理折扣请联系站内管理员。
更新日志
| 日期 | 内容 |
|---|---|
| 2026-11-21 | 网关 1.0 上线:OpenAI 兼容转发、多上游容灾、流式透传、按 token 计费、运营后台 |