Documentation

云枢 API 开发文档

OpenAI 兼容接口 · 流式输出 · 多上游容灾 · 精确计费。以下所有示例的接入地址均为 https://yunshuapi.yunshuhulian.cn/v1。

概览

云枢 API 是一个统一的国产大模型网关。你把请求发到本网关,网关按模型路由到对应上游(DeepSeek / 智谱 / 月之暗面 / 通义 / 豆包 / MiniMax 等),并把响应(含 SSE 流)实时回传。

项目值
基础地址https://yunshuapi.yunshuhulian.cn/v1
协议OpenAI Chat Completions(兼 Anthropic Messages)
鉴权Authorization: Bearer sk-ys-xxxx
流式stream: true
计费单位人民币 / 每百万 token(图像按次)
网关只做协议转发与计量,不保存你的对话内容;调用日志仅记录模型、token 数量、耗时与状态,用于计费与排障。

鉴权方式

所有接口都需要携带密钥,推荐放在请求头:

HTTP HEADER
Authorization: Bearer sk-ys-你的密钥

同时兼容以下写法,方便不同客户端:

  • x-api-key: sk-ys-xxx(Anthropic 风格)
  • ?key=sk-ys-xxx(URL 参数,仅调试用)
密钥即账户。请在控制台妥善保管,泄露后立即在后台禁用重发;网关不会通过站内信、邮件向你索要密钥。

快速开始

三步跑通:

  • 登录 控制台,粘贴密钥查看余额与可用模型;
  • 把客户端 base_url 改为 https://yunshuapi.yunshuhulian.cn/v1;
  • 填入密钥,选择模型名(见模型列表)即可对话。
cURL
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 官方一致。

参数类型说明
modelstring必填,站内模型名,如 glm-5.3
messagesarray必填,role/content 结构
streambool是否流式,默认 false
temperaturefloat采样温度
max_tokensint最大输出 token
top_p / stop / presence_penalty—原样透传上游

响应透传上游结构,额外在响应头返回:X-Relay-Request-Id、X-Relay-Upstream、X-Relay-Model,便于排障。

流式输出

设置 "stream": true 后返回 text/event-stream,网关逐块转发,不做整段缓冲。

Python
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)
若客户端提示「流中断」,通常是本地代理或 CDN 缓冲导致。网关已返回 X-Accel-Buffering: no,请确认反向代理关闭了 response buffering。

模型列表

GET /v1/models 返回当前密钥可用模型及价格。

RESPONSE
{
  "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
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。

上游若只支持 OpenAI 协议,网关会自动做字段转换;若上游本身支持 Anthropic 原生协议,则原样透传,保证长上下文与 thinking 字段完整。

计费与额度

  • 按 输入 token × 输入单价 + 输出 token × 输出单价 计费,单位 ¥/1M tokens;
  • 图像类模型按 次 计费;向量模型只计输入;
  • 余额在每次请求完成后扣除,可在控制台逐条核对明细;
  • 支持日额度上限、Key 有效期、无限额度卡;
  • 余额不足返回 401 insufficient_balance,不会产生欠费调用。

成本与售价双轨记录:后台可查看每个模型的成本、售价与毛利,方便定价。

限流与错误码

HTTPcode含义
400invalid_json / missing_model请求体不合法或缺 model
401invalid_key密钥不存在
401key_disabled / key_expired密钥被禁用或过期
401insufficient_balance余额不足
403model_forbidden该密钥无权调用此模型
404model_not_found模型未开放
429rate_limited / concurrency_limited触发 RPM 或并发限制
502upstream_error全部上游不可用(已自动重试与切换)
503upstream_not_configured该模型未绑定上游

错误体统一为:{"error":{"code":"...","message":"...","type":"yunshu_relay_error"}}。

客户端接入

客户端配置项
Cherry Studio / Chatbox / NextChat / LobeChatAPI 地址填 https://yunshuapi.yunshuhulian.cn/v1,密钥填 sk-ys-xxx,模型手填或从列表拉取
LangChainChatOpenAI(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 计费、运营后台