小鸣中转站 API 文档

多上游 OpenAI 兼容中转服务，聚合百炼（通义千问 + 万相绘图）、MiniMax、火山方舟（豆包），带 token 鉴权、限流、计费配额与完整管理后台。

快速开始

0. 拿一个 token

向管理员申请，或登录管理后台创建。token 形如 sk-xm-xxxx...

1. 列出可用模型

curl https://aigcbox.com.cn/relay/v1/models \
  -H "Authorization: Bearer sk-xm-你的密钥"

2. 文本对话

curl https://aigcbox.com.cn/relay/v1/chat/completions \
  -H "Authorization: Bearer sk-xm-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-plus","messages":[{"role":"user","content":"你好"}]}'

3. 流式输出

curl https://aigcbox.com.cn/relay/v1/chat/completions \
  -H "Authorization: Bearer sk-xm-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-plus","stream":true,"messages":[{"role":"user","content":"写一首诗"}]}'

4. 图片生成

curl https://aigcbox.com.cn/relay/v1/images/generations \
  -H "Authorization: Bearer sk-xm-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"wanx2.1-t2i-turbo","prompt":"一只戴墨镜的柴犬","size":"1024x1024","n":1}'

认证

用户端（调用 API）

Authorization: Bearer sk-xm-你的密钥

管理端（后台管理）

x-admin-token: 你的管理密钥

或通过 query 参数：?token=你的管理密钥。

可用模型

文本 / 对话

图片

API 参考

GET /relay/v1/models

列出可用模型。需 Bearer token。

{"object":"list","data":[
  {"id":"qwen-plus","object":"model","created":0,"owned_by":"xiaoming-relay"},
  {"id":"wanx2.1-t2i-turbo","object":"model","created":0,"owned_by":"xiaoming-relay-image"}
]}

GET /relay/healthz

健康检查，无需鉴权。

{"ok":true,"ts":"2026-09-07T22:46:14","uptime":"28.7s","models":7,"image_models":2}

POST /relay/v1/chat/completions

OpenAI 兼容的对话补全。

非流式响应：标准 OpenAI chat.completion 结构。流式响应：text/event-stream，标准 OpenAI SSE 格式。

POST /relay/v1/responses

Responses API（OpenAI 新协议），Codex CLI 0.147+ 专用。

POST /relay/v1/images/generations

文生图（万相）。

{"created":1234567890,"data":[{"url":"https://...","revised_prompt":null}]}

管理后台

独立 Web 入口：https://aigcbox.com.cn/relay，登录后五个页面：概览 / Token 管理 / 用量统计 / 扣费流水 / API 文档。

管理 API（供脚本调用）

以下接口需 x-admin-token header。

创建 token

curl -X POST https://aigcbox.com.cn/relay/admin/tokens \
  -H "x-admin-token: 你的管理密钥" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-token","note":"给 XX 项目用","grp":"default","rpm":60,
       "billing":0,"balance":0,"quota_tokens":0,"expires_in_days":30}'

响应（完整 token 只返回这一次）：

{"token":"sk-xm-...","name":"my-token","rpm":60,"billing":0,"balance":0,"quota_tokens":0}

计费与配额

定价（每 1K tokens，元）

图片（按张，元）

规则

• billing=0（免费）：不扣费、不限余额。
• billing=1（计费）：按上述价格扣余额；余额 ≤ 0 返回 402；配额耗尽返回 402。
• 每次请求结束才计费（拿到真实 usage 后），流式/非流式一致。
• 限流：每 token 独立 RPM，超限返回 429。

错误码

客户端接入

Codex CLI

base_url: https://aigcbox.com.cn/relay/v1
api_key: sk-xm-你的密钥
model: qwen3-coder-plus        # 或 doubao-seed-1-6-250615

Codex 0.147+ 走 /v1/responses，中转已兼容该协议。

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    base_url="https://aigcbox.com.cn/relay/v1",
    api_key="sk-xm-你的密钥",
)
resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

Node.js

const resp = await fetch("https://aigcbox.com.cn/relay/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-xm-你的密钥",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen-plus",
    messages: [{ role: "user", content: "你好" }],
  }),
});

WorkBuddy

base_url: https://aigcbox.com.cn/relay/v1
api_key: sk-xm-你的密钥

本地开发

cd xiaoming-relay
pip install -r requirements.txt
RELAY_SKIP_DB=1 RELAY_ADMIN_TOKEN=local-admin RELAY_PORT=8892 python server.py

访问：http://127.0.0.1:8892/relay

环境变量

生产部署

/home/ubuntu/relay/
├── server.py           # 中转站主程序
├── relay_secrets.py    # 独立密钥（gitignore）
├── webroot/relay.html  # 独立管理入口
├── webroot/relay-docs.html  # 本文档页
├── ecosystem.config.js # pm2 配置
└── requirements.txt

# pm2 启动
pm2 start ecosystem.config.js
pm2 save

# nginx 反代（/relay/ → 127.0.0.1:8892/relay/）
location /relay/ {
    proxy_pass http://127.0.0.1:8892/relay/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Connection "";
    proxy_read_timeout 300s;
    proxy_buffering off;
}

启动时自动执行数据库迁移（幂等）：新建缺失的表和字段，不删数据。

数据库结构

relay_tokens

relay_logs

安全说明

• 上游真实密钥（百炼 / MiniMax / 火山方舟）只在服务器 relay_secrets.py，绝不通过中转下发。
• 用户拿到的只是 sk-xm- 前缀的鉴权 token（数据库只存哈希）。
• relay_secrets.py 已加入 .gitignore，切勿提交到任何仓库。
• 建议定期轮换管理密钥 ADMIN_TOKEN。