开发文档

API 域名：api.example.com · 接口与 OpenAI Chat Completions 兼容

快速开始

先申请一个 API Key，然后任选一种方式调用。

curl

bash

curl -X POST "https://api.example.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-rian-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rian-minichat-x1",
    "messages": [{"role": "user", "content": "你是谁？"}],
    "temperature": 0.7,
    "max_tokens": 128
  }'

Python（OpenAI 官方 SDK）

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key="sk-rian-你的密钥",
)

resp = client.chat.completions.create(
    model="rian-minichat-x1",
    messages=[{"role": "user", "content": "你能做什么？"}],
    temperature=0.7,
    max_tokens=128,
)
print(resp.choices[0].message.content)
print(resp.usage)

不需要 OpenAI SDK 也能用：它就是普通的 HTTP JSON 接口，用 requests 或 fetch 直接 POST 即可。

认证

所有 /v1 接口（除自助申请外）都需要在请求头带 API Key：

http

Authorization: Bearer sk-rian-xxxxxxxxxxxxxxxxxxxx
# 或者
X-API-Key: sk-rian-xxxxxxxxxxxxxxxxxxxx

密钥形如 sk-rian- 加 43 个随机字符。服务端数据库只存 SHA-256 哈希，明文仅在申请成功那一刻返回，之后任何人和管理员都无法再次查看，丢失只能撤销后重新申请。

端点一览

方法	路径	说明	认证
POST	/v1/chat/completions	对话补全（支持流式）	需要
GET	/v1/models	模型列表	不需要
POST	/v1/keys	自助申请密钥	不需要
GET	/v1/keys/me	查看自己的密钥与今日用量	需要
DELETE	/v1/keys/me	撤销自己的密钥	需要
GET	/v1/usage/me	最近 N 天用量曲线	需要
GET	/health	健康检查	不需要

交互式调试文档见 https://<你的 API 域名>/docs（Swagger UI）。

对话补全

POST /v1/chat/completions

{
  "model": "rian-minichat-x1",
  "messages": [
    {"role": "user", "content": "你是谁？"},
    {"role": "assistant", "content": "我是 Rian 小助手。"},
    {"role": "user", "content": "你能做什么？"}
  ],
  "temperature": 0.7,
  "top_k": 40,
  "max_tokens": 128,
  "stream": false
}

请求参数

参数	类型	默认	说明
messages	array	必填	对话历史，最多 20 条，单条最多 2000 字符，最后一条应为 user
model	string	自选	填 `rian-minichat-x1`，不填也能过（单模型服务）
temperature	float	0.8	0–2。0 表示贪心解码（确定性输出）；越高越随机
top_k	int	40	本模型特有：只从概率最高的 k 个 token 里采样，0 表示关闭
max_tokens	int	256	最多生成多少个 token，上限由服务端配置决定
stream	bool	false	true 时以 SSE 流式返回
top_p / n	—	—	为兼容 OpenAI 客户端而接受，但服务端忽略

响应格式

json

{
  "id": "chatcmpl-9f2c8a1b4e6d7c3a5b8e0f1d",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "rian-minichat-x1",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "我是一个从零训练的小型语言模型。"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 14, "completion_tokens": 22, "total_tokens": 36}
}

finish_reason 为 stop 表示模型主动输出了结束符（<eos>），为 length 表示撞到了 max_tokens 上限、回复被截断。

流式输出

python

stream = client.chat.completions.create(
    model="rian-minichat-x1",
    messages=[{"role": "user", "content": "介绍一下你自己"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

服务端返回标准 SSE：每条数据形如 data: {json}，最后以 data: [DONE] 结束。倒数第二个数据块带 finish_reason 和 usage。

密钥管理

申请

bash

curl -X POST "https://api.example.com/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"name": "张三-推荐系统", "email": "zhangsan@example.com"}'

响应里的 key 字段就是明文密钥，只出现这一次。

查看自己的用量

curl "https://api.example.com/v1/keys/me" \
  -H "Authorization: Bearer sk-rian-你的密钥"

撤销自己的密钥

curl -X DELETE "https://api.example.com/v1/keys/me" \
  -H "Authorization: Bearer sk-rian-你的密钥"

错误码

HTTP	code	原因与处理
401	missing_api_key	没带 Authorization 头
401	invalid_api_key	密钥不存在或写错了
403	key_disabled	密钥被管理员停用
403	key_expired	密钥过期
400	too_many_messages	消息条数超过上限
400	message_too_long	单条消息超过字符上限
429	daily_requests_exceeded	今日请求数用满，次日 0 点重置
429	daily_tokens_exceeded	今日 token 用满，次日 0 点重置
429	rate_limit_exceeded	每分钟请求过于频繁，看 `Retry-After` 头
503	model_loading	服务刚启动还在加载模型，稍后重试

错误响应体统一为 OpenAI 风格：

{
  "error": {
    "message": "已达今日请求上限（2000 次/天）。明天自动重置，或联系管理员提高配额。",
    "type": "rate_limit_error",
    "code": "daily_requests_exceeded",
    "param": null
  }
}

配额与限流

限制	默认值	说明
每日请求数	2000 次 / Key	按自然日重置，管理员可在后台调整
每日 token 数	200,000 / Key	prompt + completion 合计
每分钟请求数	60 次 / Key	防脚本跑飞，超出返回 429
单次最大生成	256 token	由 `MAX_NEW_TOKENS` 控制
上下文上限	512 token	超出自动丢弃最老的对话轮次

使用注意

这是 13.7M 参数的微型模型，不是通用大模型。 它只能按训练过的固定话术回答常见问题，不要用它做事实查询、数学计算、代码生成或任何有准确性要求的任务。把它的输出当作「格式演示」而不是「知识来源」。

system 角色没有专门训练过：服务端会把 system 内容折进第一轮用户输入，效果不稳定，建议直接写在第一条 user 消息里。
回复长度通常较短（几十个 token），这是训练数据决定的，调大 max_tokens 不会让它变长。
同一个问题多次调用结果可能不同，需要确定性输出时把 temperature 设为 0。
中文标点、生僻字偶尔会出错，这是 8000 词表 BPE 的固有限制。