接口文档

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="")
✓
响应格式与 OpenAI 完全一致,现有解析代码、重试逻辑、LangChain / Agent 框架均无需改动。

02认证方式

所有接口使用 Bearer Token 认证。登录后在「API 密钥」页创建密钥,密钥仅创建时完整显示一次,请妥善保存。

HTTP Header
Authorization: Bearer sk-relay-xxxxxxxxxxxxxxxx
⚠
密钥泄露请立即在「API 密钥」页吊销重建,历史调用与账单不受影响。不要把密钥写在客户端代码或前端页面里。

03Base URL

环境地址
生产https://shidongai.com/v1

走 HTTPS + HTTP/2,全球 CDN 加速;SSE 流式链路已针对长静默深度思考模型做心跳保活,公网链路不会因思考期无输出而断连。

04接口列表

POST/v1/chat/completions对话补全(支持流式)
POST/v1/completions文本补全(兼容旧接口)
POST/v1/embeddings文本向量化
POST/v1/images/generations图片生成
GET/v1/models可用模型列表(含定价扩展字段)
POST/v1/videos/generations视频生成暂未开放

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
streambooltrue 时返回 SSE 流式增量,默认 false
temperaturenumber采样温度,默认 0.7
max_tokensint生成上限,同时影响计费预估
toolsarray函数调用定义,原样透传

请求示例

JSON
{
  "model": "glm-5.3",
  "messages": [
    {"role": "system", "content": "你是一个乐于助人的助手"},
    {"role": "user", "content": "你好"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024
}

响应示例

JSON
{
  "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 帧序列

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 流式示例

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)
ℹ
上游未返回 usage 的模型,网关会按实际流量合成 usage chunk 注入流尾,计费口径始终有据可查。

07Embeddings

POST /v1/embeddings —— 文本向量化,请求/响应与 OpenAI 一致。

curl
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),响应体含各模型定价扩展字段。

Response
{
  "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%
✓
把长系统提示词放在 messages 最前面、保持前缀稳定,可最大化缓存命中,多轮会话输入成本直降一个数量级。

10计费说明

  • 按 token 计费,输入 / 输出 / 缓存读分别计价,价格与折扣见定价页
  • 每笔请求先预扣估算最大费用,完成后按实际用量结算,多退少补
  • 高峰时段(8:00 – 22:00)与空闲时段(22:00 – 次日 8:00)价格不同,自动按请求时间判定,无需配置
  • 余额不足返回 402 insufficient_balance,充值后重试
  • 用量、费用、缓存命中率在用户中心实时可查,支持自助开票

11错误码

HTTP错误类型说明与处理
401invalid_api_key密钥缺失 / 无效 / 已吊销 — 检查 Authorization 头或重建密钥
402insufficient_balance余额不足 — 充值后重试;预扣在请求开始时冻结
404model_not_found模型不存在或未开放 — 核对 model 字段
429rate_limit_exceeded触发限流 — 响应体含具体限制(RPM / TPM),按 Retry-After 退避重试
503capacity_exceeded网关繁忙 — 容量保护,稍后重试
502/504upstream_error上游渠道异常 — 网关自动故障转移,持续失败请联系我们

错误响应体为 OpenAI 风格:{"error": {"message": "...", "type": "...", "code": "..."}}

12速率与并发

  • 默认按账户维度限流(RPM / TPM),触发时返回 429 并携带具体限制类型
  • 网关内置多渠道 Key 池与健康检查,上游异常自动切换,无需客户端处理
  • 请求体超过 16KB 可启用 gzip 压缩(携带 Content-Encoding: gzip),网关自动解压
  • 更高并发需求请联系商务调整配额

13SDK 兼容性

替换 Base URL 即可,现有代码零改动:

✓ OpenAI Python SDK ✓ OpenAI Node SDK ✓ LangChain / LlamaIndex ✓ Function Calling ✓ SSE 流式 ✓ 世东 AI 桌面智能体
功能OpenAI API世东
Chat Completions✓ /v1/chat/completions✓ 完全兼容
Streaming (SSE)✓ stream: true✓ 支持
Function Calling✓ tools✓ 透传
上下文缓存—✓ 自动生效
峰谷分时计价—✓ 自动折扣
多渠道故障转移—✓ 自动切换
→
准备好开始了吗?登录创建密钥,一分钟完成首次调用。获取 API Key →