API 文档 · AI Token 中转站

概述

服务地址（Base URL）：

所有 API 均支持跨域（CORS），可直接在浏览器或任意 HTTP 客户端中调用。健康检查：

GET /health

认证方式

调用 AI 接口和余额查询时，需在请求头中携带 API Token：

Authorization: Bearer sk-relay-xxxxxxxx

Token 由管理员在后台创建并充值余额。Token 无效、已禁用或余额不足时，请求将被拒绝。

对话补全

POST /v1/chat/completions 需要 Bearer Token

与 OpenAI Chat Completions API 完全兼容，支持流式（stream: true）和非流式响应。请求体格式与 OpenAI 一致。

请求示例

curl /v1/chat/completions \
  -H "Authorization: Bearer sk-relay-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V3",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ]
  }'

流式请求

curl /v1/chat/completions \
  -H "Authorization: Bearer sk-relay-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V3",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

响应说明

非流式响应会在 JSON 中返回 usage 字段（包含 token 用量）。请求成功后按实际用量扣费，响应头中包含 X-Usage-Cost-Yuan 表示本次费用（元）。

余额预检：发送请求前会估算最大可能费用并检查余额。余额不足时返回 402 错误，不会转发到上游。

模型列表

GET /v1/models 无需认证

获取上游支持的模型列表，响应格式与 OpenAI 一致。

curl /v1/models

查询余额

GET /v1/balance 需要 Bearer Token

查询当前 Token 的账户余额，适合在程序中定期检查余额。

curl /v1/balance \
  -H "Authorization: Bearer sk-relay-xxx"

响应示例

{
  "data": {
    "name": "测试用户",
    "balance": 9.523400,
    "balance_yuan": "9.523400"
  }
}

用量查询

GET /api/usage Query 参数传 Token

查询 Token 的用量明细与余额，支持分页。也可在首页通过网页查询。

请求参数

参数	必填	说明
`token`	是	API Token（sk-relay-xxx）
`page`	否	页码，默认 1
`page_size`	否	每页条数，默认 20，最大 100

curl '/api/usage?token=sk-relay-xxx&page=1&page_size=20'

响应示例

{
  "token": {
    "name": "测试用户",
    "balance_yuan": "9.523400",
    "token_masked": "sk-relay...xxxx"
  },
  "data": [
    {
      "id": "...",
      "model": "deepseek-ai/DeepSeek-V3",
      "prompt_tokens": 120,
      "completion_tokens": 85,
      "cached_input_tokens": 0,
      "uncached_input_tokens": 120,
      "cost_yuan": "0.000850",
      "balance_after_yuan": "9.523400",
      "created_at": "2026-06-17 12:00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "total_pages": 3
  }
}

计费规则

按实际 token 用量计费，每次请求完成后从余额中扣除。

类型	单价（每百万 tokens）
输入（缓存命中）	¥0.025
输入（缓存未命中）	¥5
输出	¥10

输入 token 会根据上游返回的缓存命中/未命中信息分别计费。余额不足时接口返回 402，不会消耗上游配额。

SDK 接入

任何支持自定义 base_url 的 OpenAI 兼容客户端均可使用，以下是 Python 和 Node.js 示例。

Python（openai SDK）

from openai import OpenAI

client = OpenAI(
    api_key="sk-relay-xxx",
    base_url="/v1"
)

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V3",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

Node.js（openai SDK）

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-relay-xxx",
  baseURL: "/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-ai/DeepSeek-V3",
  messages: [{ role: "user", content: "你好" }],
});
console.log(response.choices[0].message.content);

Cursor / 其他工具

在 Cursor 或其他 AI 工具中，将 API Base URL 设为本站地址加 /v1 后缀，API Key 填入分配的 Token 即可。

错误码

错误响应格式统一为：

{
  "error": {
    "message": "错误描述",
    "type": "error_type",
    "code": "optional_code"
  }
}

HTTP 状态码	type / code	说明
401	`authentication_error`	Token 无效、缺失或已禁用
402	`insufficient_quota`	余额不足
400	`invalid_request_error`	请求参数错误
404	`not_found_error`	资源不存在（如无效 Token 查询用量）
500	`server_error`	服务器内部错误