接入文档 · OpenAI 兼容

改一行 base_url 就能用

已有 OpenAI 的 SDK 或插件,把地址和 Key 换掉即可,代码基本不用动。改 model 名就能切换不同模型。

快速开始

三步拿到第一个回复。

1. 注册并创建 API Key

注册后在控制台 → API Key 新建一个。Key 只在创建时显示一次,请立即保存。

2. 设置 base_url

BASE_URL
https://yun.nmgshenghang.cn/v1

3. 发一次请求

curl
curl https://yun.nmgshenghang.cn/v1/chat/completions \
  -H "Authorization: Bearer $SHSL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [{"role": "user", "content": "你好"}]
  }'
Python(openai 官方 SDK)
from openai import OpenAI

client = OpenAI(
    api_key="sk-shsl-...",
    base_url="https://yun.nmgshenghang.cn/v1"
)

r = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "你好"}]
)
print(r.choices[0].message.content)
Node.js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-shsl-...",
  baseURL: "https://yun.nmgshenghang.cn/v1"
});

const r = await client.chat.completions.create({
  model: "glm-5.3",
  messages: [{ role: "user", content: "你好" }]
});
console.log(r.choices[0].message.content);

鉴权

所有接口都在请求头带 Key。

Header
Authorization: Bearer sk-shsl-xxxxxxxxxxxxxxxx
一个 Key 通用。不需要为不同模型、不同供应商分别申请 Key。额度从账户余额扣。
不要把 Key 写进前端代码或公开仓库。浏览器里调用会暴露 Key,正确做法是放你自己的服务端中转。

模型选择

25 个模型统一接口,价格与上下文长度都明码标注。

同一模型可能由多个通道供货,切换只改 model 字符串:

命名规则
glm-5.3            → 通道一
glm-5.3-oc         → 通道二(如已开通)

能力完全相同,价格可能不同。切换只改 model,Key 不变。

下表是当前可调用的模型(打开页面时实时拉取,加模型后自动更新):

model(调用时填这个)名称供应商类型 输入价输出价单位上下文
正在加载…
完整清单也可以直接问接口:GET /v1/models(需要 Key)。

对话补全

POST /v1/chat/completions

请求体
{
  "model": "glm-5.3",
  "messages": [
    {"role": "system", "content": "你是一个简洁的助手"},
    {"role": "user",   "content": "你好"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}
响应
{
  "id": "req-6e8e665f265c1ad5779c0271",
  "object": "chat.completion",
  "model": "glm-5.3",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "你好!有什么可以帮你?"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 18, "completion_tokens": 12, "total_tokens": 30}
}

支持的参数

参数说明
model 必填见「模型选择」的表格
messages 必填role 支持 system / user / assistant / tool
temperature0~2,越大越发散
top_p0~1,与 temperature 二选一
max_tokens最大输出长度
streamtrue 时返回 SSE 流
stop停止词,字符串或数组
tools / tool_choice函数调用,与 OpenAI 一致
response_format如 {"type":"json_object"}

流式输出

stream 设为 true,服务端以 SSE 逐块返回。

Python 流式
stream = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "写一段 200 字的介绍"}],
    stream=True
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
流式请求的 usage(token 数)在最后一帧返回。自己解析 SSE 时记得处理 data: [DONE]。

工具调用

与 OpenAI function calling 格式完全一致。

定义工具
{
  "model": "glm-5.3",
  "messages": [{"role": "user", "content": "北京今天天气怎么样"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询城市天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
不是所有模型都支持工具调用。模型表里带「工具」标记的才支持。

图片理解

content 换成数组,图片传 URL 或 base64。仅支持带视觉能力的模型。

请求
{
  "model": "deepseek-v4.1-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "这张图里有什么"},
      {"type": "image_url", "image_url": {"url": "https://example.com/a.jpg"}}
    ]
  }]
}

文本向量 暂未开放

POST /v1/embeddings

平台目前尚未接入向量模型,调用会返回 no_upstream。接口已按 OpenAI 规范实现,接入后下面示例可直接使用。
请求 / 响应
{"model": "bge-m3", "input": ["第一段文本", "第二段文本"]}

→ {"data": [{"index": 0, "embedding": [0.013, -0.024, ...]}, ...],
   "usage": {"prompt_tokens": 12, "total_tokens": 12}}

图像生成

POST /v1/images/generations · 按张计费

请求 / 响应
{
  "model": "qwen-image-3.0",
  "prompt": "一只橘猫坐在窗台上,午后阳光",
  "n": 1,
  "size": "1024x1024"
}

→ {
  "created": 1792635822,
  "data": [{"url": "https://dashscope-....png"}],
  "usage": {"images": 1, "cost_cents": 18, "cost_yuan": 0.18}
}
返回的是图片 URL(不是 base64)。出图通常 20~60 秒,超时要设长。

视频生成

异步两步:创建任务 → 轮询结果。按秒计费。

① 创建
{
  "model": "minimax-h3-max",
  "prompt": "海边的日落,慢镜头",
  "duration": 6,
  "ratio": "16:9",
  "resolution": "768P"
}

→ {"id":"455001208295701","status":"queued","poll_url":"/v1/videos/455001208295701","usage":{"seconds":6,"cost_yuan":3}}
② 轮询
GET /v1/videos/455001208295701
Authorization: Bearer $SHSL_API_KEY

→ {"id":"455001208295701","status":"succeeded","video_url":"https://..."}
参数取值
duration秒数,例如 5 / 6 / 10
ratio16:9、4:3、1:1、3:4、9:16、21:9(不能是 adaptive)
resolution480P、768P
statusqueued → processing → succeeded / failed

语音合成 暂未开放

POST /v1/audio/speech · 按万字符计费

平台目前尚未接入语音合成模型,调用会返回 no_upstream。接口已按 OpenAI 规范实现,接入后即可使用。
请求 / 响应
{
  "model": "cosyvoice-v3.5-flash",
  "input": "你好,这是一段测试语音",
  "voice": "<音色ID>",
  "response_format": "mp3",
  "speed": 1.0
}

→ {"url": "https://...mp3", "chars": 12, "usage": {"characters": 12, "cost_yuan": 0.001}}
voice 必填。cosyvoice 系列没有系统音色,需要先在控制台创建「声音复刻 / 声音设计」音色。

模型列表 / 我的额度

两个查询接口。

查询
GET /v1/models      # 当前可调用的模型(含价格、上下文、能力)
GET /v1/me          # 我的余额与额度

错误码

HTTPtype含义怎么处理
401authentication_errorKey 缺失或无效检查 Authorization 头
402insufficient_balance余额不足控制台充值
404model_not_found模型不存在或已下架用 GET /v1/models 查可用名
429rate_limit_exceeded触发限流指数退避重试
502upstream_error上游供应商异常换同模型的其他供应商重试
400invalid_request_error参数不合法看 error.message
错误体格式
{"error": {"message": "模型不存在或已下线: xxx", "type": "model_not_found", "code": "model_not_found"}}

计费与限流

类型算法单位
文本输入 tokens ÷ 1,000,000 × 输入价 + 输出 tokens ÷ 1,000,000 × 输出价元 / 百万 tokens
图像张数 × 单价元 / 张
视频时长秒数 × 单价元 / 秒
语音字符数 ÷ 10,000 × 单价元 / 万字符
  • 预付费,从账户余额扣,余额不足直接返回 402,不会产生欠费
  • 费用向上取整到分
  • 每次调用的 token 数、耗时、费用都可在控制台「用量统计」查

限流

  • 默认每 Key 60 次/分钟,突发上限 20
  • 需要更高并发,联系客服单独调整

接入建议

  • 先在服务端落地:不要从浏览器直连,Key 会泄露
  • 超时设长:文本 60 秒、图像 180 秒;视频只看创建接口(很快),轮询单独设
  • 502 先重试,再换档位:多数是瞬时抖动;持续失败就改用同系列其他模型(如 glm-5.3 → glm-5.3-flash)
  • 429 退避:1s → 2s → 4s,别死循环
  • temperature 从低试:结构化输出先用 0~0.3
  • 长文本注意上下文:模型表里标了每个模型的上限

让 AI 帮你写代码

三种机器可读格式,直接喂给任何 AI 助手就能生成可运行的调用代码。

地址格式适合
/llms.txt纯文本直接粘贴给 ChatGPT / Claude / 豆包等对话助手
/docs/api.mdMarkdown喂给 AI 或放进知识库
/openapi.jsonOpenAPI 3.0Apifox / Postman / Cursor 等工具

用法一:直接把链接丢给 AI

复制这段话发给 AI
请先读取 https://yun.nmgshenghang.cn/llms.txt 这份接口文档,
然后帮我用 Python 写一个封装类:
支持流式输出、工具调用、失败自动重试
(502 时换同模型的其他供应商,429 时指数退避)。
不要用占位符,给出可以直接运行的完整代码。

用法二:把文件内容直接粘贴进去

打开 /llms.txt,全选复制,粘贴到对话里,再说「按这份文档帮我接入」。里面已经把模型清单、各家价格、接口示例、错误码、计费规则都写全了。

用法三:用 OpenAPI 自动生成

Apifox / Postman / Swagger Editor 导入 /openapi.json,得到完整接口集合与模型枚举,可以直接调试。