接口文档
OpenAI 协议完全兼容——替换 Base URL 即可迁移现有代码,支持流式、缓存计费与故障转移。
01快速开始
已有 OpenAI SDK?三步完成接入:
- 注册并登录,在「API 密钥」页创建
sk-relay-*密钥 - 替换
base_url为https://shidongai.com/v1 - model 换成任一可用模型,开始调用
# pip install openai — 无需额外依赖 from openai import OpenAI client = OpenAI( api_key="sk-relay-your-key", base_url="https://shidongai.com/v1" ) response = client.chat.completions.create( model="glm-5.3-flash", messages=[{"role": "user", "content": "你好"}], stream=True ) for chunk in response: print(chunk.choices[0].delta.content or "", end="")
02认证方式
所有接口使用 Bearer Token 认证。登录后在「API 密钥」页创建密钥,密钥仅创建时完整显示一次,请妥善保存。
Authorization: Bearer sk-relay-xxxxxxxxxxxxxxxx
03Base URL
| 环境 | 地址 |
|---|---|
| 生产 | https://shidongai.com/v1 |
走 HTTPS + HTTP/2,全球 CDN 加速;SSE 流式链路已针对长静默深度思考模型做心跳保活,公网链路不会因思考期无输出而断连。
04接口列表
05对话补全
POST /v1/chat/completions —— 核心接口,与 OpenAI Chat Completions 同构,支持 system / user / assistant 多轮对话、函数调用(tools)与 JSON 模式。
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| model 必填 | string | 模型名,见 模型广场 或 GET /v1/models |
| messages 必填 | array | 对话历史,role: system / user / assistant / tool |
| stream | bool | true 时返回 SSE 流式增量,默认 false |
| temperature | number | 采样温度,默认 0.7 |
| max_tokens | int | 生成上限,同时影响计费预估 |
| tools | array | 函数调用定义,原样透传 |
请求示例
{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "你是一个乐于助人的助手"},
{"role": "user", "content": "你好"}
],
"stream": false,
"temperature": 0.7,
"max_tokens": 1024
}
响应示例
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1788888888,
"model": "glm-5.3",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "你好!有什么可以帮你?"},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 9,
"total_tokens": 21,
"prompt_tokens_details": {"cached_tokens": 8}
}
}
usage 中的 cached_tokens 表示命中上下文缓存的输入 token 数,该部分按缓存价计费(详见上下文缓存)。
06流式响应
设置 "stream": true 后,响应为 SSE 流,每行 data: {...},以 data: [DONE] 结束。网关在长静默期(深度思考模型)自动发送心跳注释帧保持链路。
SSE 帧序列
: ka # 心跳注释帧(长静默期,客户端可忽略) data: {"id":"chatcmpl-xxx","choices":[{"delta":{"role":"assistant"}}]} data: {"choices":[{"delta":{"content":"你好"}}]} data: {"choices":[{"delta":{},"finish_reason":"stop"}]} data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9}} # include_usage 时 data: [DONE]
Python 流式示例
stream = client.chat.completions.create( model="glm-5.3", messages=[{"role": "user", "content": "写一首短诗"}], stream=True, stream_options={"include_usage": True}, # 末尾 chunk 携带 usage ) for chunk in stream: delta = chunk.choices[0].delta if chunk.choices else None if delta and delta.content: print(delta.content, end="", flush=True)
07Embeddings
POST /v1/embeddings —— 文本向量化,请求/响应与 OpenAI 一致。
curl https://shidongai.com/v1/embeddings \ -H "Authorization: Bearer sk-relay-your-key" \ -H "Content-Type: application/json" \ -d '{"model":"embedding-model","input":"世东模型服务平台"}'
08模型列表
GET /v1/models —— 返回当前可用的模型目录,带 ETag 缓存(If-None-Match 命中返回 304),响应体含各模型定价扩展字段。
{
"object": "list",
"data": [
{"id": "glm-5.3", "object": "model", "owned_by": "shidong", ...},
{"id": "glm-5.3-flash", ...}
]
}
09上下文缓存
前缀缓存自动生效,无需任何参数。当多次请求共享相同前缀(系统提示词、知识库文档、多轮对话历史)时,重复部分按缓存价计费,约为标准输入价的 1/10。
- 命中时响应 usage 携带
prompt_tokens_details.cached_tokens,未命中时该字段不出现 - 命中率 = cached_tokens / prompt_tokens
- 重复的 system 与历史前缀、连续调用更易命中
- 智能体场景(固定系统提示 + 变化问题)实测命中率可达 99.2%
10计费说明
- 按 token 计费,输入 / 输出 / 缓存读分别计价,价格与折扣见定价页
- 每笔请求先预扣估算最大费用,完成后按实际用量结算,多退少补
- 高峰时段(8:00 – 22:00)与空闲时段(22:00 – 次日 8:00)价格不同,自动按请求时间判定,无需配置
- 余额不足返回
402 insufficient_balance,充值后重试 - 用量、费用、缓存命中率在用户中心实时可查,支持自助开票
11错误码
| HTTP | 错误类型 | 说明与处理 |
|---|---|---|
| 401 | invalid_api_key | 密钥缺失 / 无效 / 已吊销 — 检查 Authorization 头或重建密钥 |
| 402 | insufficient_balance | 余额不足 — 充值后重试;预扣在请求开始时冻结 |
| 404 | model_not_found | 模型不存在或未开放 — 核对 model 字段 |
| 429 | rate_limit_exceeded | 触发限流 — 响应体含具体限制(RPM / TPM),按 Retry-After 退避重试 |
| 503 | capacity_exceeded | 网关繁忙 — 容量保护,稍后重试 |
| 502/504 | upstream_error | 上游渠道异常 — 网关自动故障转移,持续失败请联系我们 |
错误响应体为 OpenAI 风格:{"error": {"message": "...", "type": "...", "code": "..."}}
12速率与并发
- 默认按账户维度限流(RPM / TPM),触发时返回 429 并携带具体限制类型
- 网关内置多渠道 Key 池与健康检查,上游异常自动切换,无需客户端处理
- 请求体超过 16KB 可启用 gzip 压缩(携带
Content-Encoding: gzip),网关自动解压 - 更高并发需求请联系商务调整配额
13SDK 兼容性
替换 Base URL 即可,现有代码零改动:
| 功能 | OpenAI API | 世东 |
|---|---|---|
| Chat Completions | ✓ /v1/chat/completions | ✓ 完全兼容 |
| Streaming (SSE) | ✓ stream: true | ✓ 支持 |
| Function Calling | ✓ tools | ✓ 透传 |
| 上下文缓存 | — | ✓ 自动生效 |
| 峰谷分时计价 | — | ✓ 自动折扣 |
| 多渠道故障转移 | — | ✓ 自动切换 |