API 文档 — 词元宝 · 统一 API 网关

🚀 快速开始

词元宝 API 完全兼容 OpenAI 接口格式，只需修改 base_url 即可接入

POST https://api.ciyuanbao.net/v1/chat/completions 基础地址

# 使用 curl 发送第一个请求
curl https://api.ciyuanbao.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "介绍一下词元宝"}]
  }'

# Python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.ciyuanbao.net/v1"
)
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "介绍一下词元宝"}]
)
print(response.choices[0].message.content)

// Node.js
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.ciyuanbao.net/v1'
});

const response = await client.chat.completions.create({
  model: 'deepseek-v4-pro',
  messages: [{ role: 'user', content: '介绍一下词元宝' }]
});
console.log(response.choices[0].message.content);

🔑 认证鉴权

所有 API 请求需要在 HTTP Header 中携带 API Key

登录控制台 → API 密钥 页面获取你的 API Key。
Key 以 sk- 开头，请妥善保管，不要提交到代码仓库或暴露在客户端。

Authorization: Bearer sk-wbxxxxxxxxxxxxxxxxxxxxxxxx

参数	类型	说明
Authorization	Header	格式: `Bearer sk-your-key`

💬 Chat Completions

创建聊天补全，支持多轮对话、Function Calling、JSON模式

POST /v1/chat/completions

参数	类型	必填	说明
model	string	✓	模型ID，如 `deepseek-v4-pro`，设为 `auto` 启用智能路由
messages	array	✓	对话消息列表，每条含 `role` 和 `content`
max_tokens	integer	—	最大输出 Token 数，默认 1024
temperature	float	—	随机性 0-2，默认 0.7
stream	boolean	—	是否启用 SSE 流式输出，默认 false
top_p	float	—	核采样阈值 0-1，默认 1
stop	string/array	—	停止词
tools	array	—	Function Calling 工具定义

📡 流式输出 (SSE)

设置 stream: true 启用 SSE 流式输出，返回格式与 OpenAI 兼容

# 流式请求示例
curl https://api.ciyuanbao.net/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"你好"}],"stream":true}'

# 响应示例（每行为 data: 前缀的JSON）
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"你"}}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"delta":{"content":"好"}}]}
data: [DONE]

# Python 流式示例
for chunk in client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role":"user","content":"你好"}],
    stream=True
):
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

🧠 模型列表

获取当前可用的模型列表及详细信息

GET /v1/models

# 获取模型列表
curl https://api.ciyuanbao.net/v1/models \
  -H "Authorization: Bearer sk-xxx"

# 响应示例
{
  "object": "list",
  "data": [
    {"id":"deepseek-v4-pro", "vendor":"深度求索", "category":"text", "context":"1M", "price":"1.5/M"},
    {"id":"qwen-3.6-plus", "vendor":"阿里云", "category":"text", "context":"128K", "price":"2.0/M"}
  ]
}

🧭 智能路由

设置 model: "auto" 启用智能路由，系统自动选择最优模型

路由策略	说明	适用场景
`cost_first`	优先选择成本最低的可用模型	对成本敏感的大批量调用
`quality_first`	优先选择综合质量最高的模型	对回答质量要求高的场景
`latency_first`	优先选择当前延迟最低的模型	实时交互场景

{
  "model": "auto",
  "route_strategy": "cost_first",
  "messages": [...]
}

⚠️ 错误码

标准 HTTP 状态码 + JSON 错误体

400请求参数错误

401API Key 无效或过期

402账户余额不足

429请求频率超限

500服务器内部错误

503模型暂时不可用

{
  "error": {
    "code": "insufficient_balance",
    "message": "账户余额不足，请充值后重试",
    "type": "payment_required"
  }
}

📦 SDK 接入

多语言 SDK，一行代码切换至词元宝

# Python — pip install openai
from openai import OpenAI
client = OpenAI(api_key="sk-xxx", base_url="https://api.ciyuanbao.net/v1")

// Node.js — npm install openai
import OpenAI from 'openai';
const client = new OpenAI({ apiKey: 'sk-xxx', baseURL: 'https://api.ciyuanbao.net/v1' });

// Java — OkHttp + Jackson
OkHttpClient http = new OkHttpClient();
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));
Request req = new Request.Builder()
    .url("https://api.ciyuanbao.net/v1/chat/completions")
    .header("Authorization", "Bearer sk-xxx")
    .post(body).build();

📊 速率限制

版本	速率	日配额
免费版	10 次/分钟	500 次/天
专业版 ¥169/月	60 次/分钟	无限制
企业版 ¥699/月	300 次/分钟	可定制

超限返回 HTTP 429，建议客户端实现指数退避重试：wait = min(60, 2 ** retry_count)