快速开始
整个接入过程只有三个动作：拿 Key、改 base_url、发请求。没有任何需要编译或安装的平台组件。
- 在控制台创建 API Key（形如 sk-sit-…），并记录一次，页面关闭后不再完整显示
- 把请求地址指向 https://api.siteng.xin/v1
- 沿用你现在的 OpenAI SDK 与调用代码，把 model 换成目标模型 ID
Python 最小示例
quickstart.py
# 装好 openai 之后，只改两处：api_key 与 base_url from openai import OpenAI client = OpenAI( api_key="sk-sit-••••••••••••", # 控制台创建的 Key base_url="https://api.siteng.xin/v1", ) resp = client.chat.completions.create( model="deepseek-v4", messages=[{"role": "user", "content": "用三句话说明什么是 RAG"}], ) print(resp.choices[0].message.content) print(resp.usage.total_tokens) # 这次调用了多少 Token，账单里就是这个数
示例里的 Key 请替换成你自己的。生产环境不要把 Key 写进代码，用环境变量或密钥管理服务注入。
认证
所有请求通过 Authorization 头认证，格式为 Bearer + 空格 + API Key。Key 与账号绑定，可在控制台按子账号、按模型、按额度上限分别签发。
- 一个账号可以创建多个 Key，建议按环境（开发 / 测试 / 生产）或按业务线分开，便于单独吊销与统计
- Key 只在创建时完整显示一次，之后仅显示前缀；丢失请直接重新签发，不要试图找回
- 可为单个 Key 设置额度上限、有效期与 IP 白名单，防止泄漏后被无限使用
- Key 泄漏时在控制台立即吊销，吊销后所有在途请求会立即失效
shell
# Key 放在 Authorization 头里，前缀固定为 Bearer curl https://api.siteng.xin/v1/chat/completions \ -H "Authorization: Bearer sk-sit-••••••••••••" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-v4", "messages": [{"role": "user", "content": "你好"}], "stream": false }'
第一个请求
整个接入过程只有三个动作：拿 Key、改 base_url、发请求。没有任何需要编译或安装的平台组件。
quickstart.mjs
import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.SITENG_API_KEY, baseURL: "https://api.siteng.xin/v1", }); const resp = await client.chat.completions.create({ model: "deepseek-v4", messages: [{ role: "user", content: "用三句话说明什么是 RAG" }], }); console.log(resp.choices[0].message.content);
端点总览
全部端点都在同一域名下，路径与 OpenAI 保持一致，因此现有 SDK 不需要任何适配代码。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /v1/chat/completions | 对话与推理，支持流式与非流式 |
| POST | /v1/completions | 文本补全，兼容旧版调用方式 |
| POST | /v1/embeddings | 文本向量化，用于检索与聚类 |
| POST | /v1/rerank | 检索结果重排，配合向量召回使用 |
| POST | /v1/audio/speech | 语音合成，输出音频流 |
| GET | /v1/models | 查询当前账号可用的模型与单价 |
对话接口是本平台的主接口：15 个对话与多模态模型全部走同一个端点，换模型只改 model 参数，不改路径、不改请求结构。
请求参数
以下为对话接口的主要参数。未列出的 OpenAI 标准参数同样被接受，未知参数会被忽略而不是报错。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型 ID，取值见模型广场，例如 deepseek-v4 |
messages | array | 是 | 对话消息数组，role 支持 system / user / assistant / tool |
stream | boolean | 否 | 是否流式返回，默认 false |
max_tokens | integer | 否 | 最大输出 Token 数，默认由模型自身上限决定 |
temperature | number | 否 | 采样温度，0–2，默认 1；数值越低输出越确定 |
top_p | number | 否 | 核采样阈值，0–1，默认 1；与 temperature 建议只调一个 |
tools | array | 否 | 工具定义数组，用于函数调用 |
stream_options | object | 否 | 设为 include_usage 为 true 时，流式最后一块返回本次用量 |
流式输出
把 stream 设为 true 即开启 SSE 流式返回。适合对话类界面：首字更早出现，用户不需要等整段生成完。计量口径与非流式完全一致，不会因为流式而多算。
stream.py
stream = client.chat.completions.create( model="deepseek-v4", messages=[{"role": "user", "content": "写一段产品介绍"}], stream=True, stream_options={"include_usage": True}, # 最后一块带用量，便于对账 ) for chunk in stream: delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True)
请务必处理连接中断：流式过程中网络断开时，已产出的部分仍会计费，客户端应保存已收到的内容并支持续写，而不是从头重发。
工具调用
支持 OpenAI 标准的 tools 参数。模型只负责决定「调用哪个函数、传什么参数」，真正的执行由你的业务代码完成，再把结果作为 tool 消息回传。
tools.py
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
resp = client.chat.completions.create(
model="kimi-k2.7",
messages=[{"role": "user", "content": "杭州今天要带伞吗"}],
tools=tools,
)
call = resp.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments) # 由你来执行，再把结果回传
不是所有模型都支持工具调用。智能体类模型（Kimi-K2.7、GLM-5.3、Qwen3-Coder-480B、MiniMax-M2.5）表现更稳，模型广场可按「智能体」分类筛选。
错误码
错误响应遵循 OpenAI 格式，包含 error.type、error.code 与 error.message 三个字段。建议按 code 分支处理，不要解析 message 文案（文案可能调整）。
| HTTP | code | 含义与处理建议 |
|---|---|---|
| 400 | invalid_request_error | 参数缺失或格式错误。检查必填字段与 JSON 结构，不要重试 |
| 401 | authentication_error | Key 无效、已吊销或缺少 Bearer 前缀。确认请求头后重新签发 |
| 402 | insufficient_balance | 余额不足。充值，或换用仍有额度的 Key；不会自动续费 |
| 403 | permission_denied | 该 Key 未被授权访问此模型。在控制台为 Key 勾选模型范围 |
| 404 | model_not_found | 模型不存在或已下线。调用 /v1/models 拉取最新清单 |
| 408 | request_timeout | 上游超时未产出内容。可重试；长任务建议改用流式 |
| 413 | payload_too_large | 请求体超过大小限制。缩短上下文或分段处理 |
| 429 | rate_limit_exceeded | 触发速率或并发上限。按指数退避重试；需要更高配额请联系商务 |
| 500 | internal_error | 平台内部错误。退避重试，持续出现请提工单并附请求 ID |
| 503 | upstream_unavailable | 上游通道暂时不可用。平台会自动切换备用通道，稍后重试即可 |
限流与配额
默认速率与并发按账号等级下发，企业账号显著更高。所有限额都可以在控制台实时查看水位，不需要靠 429 去试。
- 维度：按账号、按 Key、按模型三层分别限额，任何一层超限都会返回 429
- 建议：客户端做指数退避（1s / 2s / 4s）并加随机抖动，避免重试风暴
- 提额：有明显峰值或批量任务，在商务阶段说明规模，我们会提前做容量预留
- 隔离：单个 Key 的额度上限可以设死，避免一个业务线吃掉整个账号的额度
SDK 与示例
因为协议完全兼容，你直接用官方 OpenAI SDK 即可，不需要我们单独维护的客户端。任何支持自定义 base_url 的 OpenAI 兼容库都能用。
| 语言 | 依赖 | 说明 |
|---|---|---|
| Python | openai | pip install openai，改 base_url 即可 |
| Node.js | openai | npm i openai，用法与官方文档一致 |
| Java | openai-java | 官方 openai-java，支持流式与工具调用 |
| Go | go-openai | go-openai 或 sashabaranov 系列库均可 |
| 其他 | — | 任何 OpenAI 兼容客户端，仅需支持自定义 base_url |
Node.js 示例
quickstart.mjs
import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.SITENG_API_KEY, baseURL: "https://api.siteng.xin/v1", }); const resp = await client.chat.completions.create({ model: "deepseek-v4", messages: [{ role: "user", content: "用三句话说明什么是 RAG" }], }); console.log(resp.choices[0].message.content);
向量召回 + 重排组合
embed.py
# 召回：BGE-M3 把文本变成向量 emb = client.embeddings.create(model="bge-m3", input=["合同里的违约责任怎么写"]) vec = emb.data[0].embedding # 精排：把候选片段交给重排模型打分 ranked = client.post("/rerank", body={ "model": "bge-reranker-v2", "query": "合同里的违约责任怎么写", "documents": candidates, # 上一步召回的 20 条 "top_n": 6, }) # 把 top 6 交给生成模型，通常比直接把 20 条塞进上下文更准、更省
常见问题
需要改我现有的代码吗？
基本不需要。把 base_url 改成我们的地址、api_key 换成我们的 Key 即可。原有调用逻辑、SDK、提示词模板全部可以继续使用。已验证 Python、Node.js、Java、Go 的官方 OpenAI SDK 都能直接跑通。
能指定某个模型的固定版本吗？
可以。控制台模型广场里每个模型都会列出可用的版本 ID（如带日期后缀的版本）。指向具体版本后，上游升级不会自动影响你；不指定版本时默认走最新稳定版。
失败请求会计费吗？
不会。返回 4xx / 5xx 且没有产出的请求不计费；如果上游已经产出部分内容后失败，按实际产出的 Token 计费。账单里每笔扣费都能对应到具体请求 ID。
怎么确认实际用量和账单对得上？
每次响应都返回 usage 字段；流式请求把 stream_options 的 include_usage 设为 true，最后一块也会带用量。控制台账单可按天、按模型、按 Key 导出明细，与 usage 累加值一致。