Skip to content

API_CONTRACT.md

Latest commit

 

History

History
311 lines (236 loc) · 7.02 KB

API_CONTRACT.md

File metadata and controls

311 lines (236 loc) · 7.02 KB

TokenRouter API Contract

所有 HTTP 接口的规范定义。任何实现必须与此文档保持一致。 最后更新：2026-04-16

1. 基础约定

1.1 Base URL

由部署环境决定，例如：http://localhost:8080

1.2 认证

所有业务接口（除 /health 外）必须在 Authorization Header 中携带 Bearer Token：

Authorization: Bearer {api_key}
  • API Key 格式示例：tr-test-xxx 或 sk-tr-xxx
  • 缺失或错误的 Key 返回 401 Unauthorized

1.3 内容类型

  • 请求体：application/json
  • 流式响应：text/event-stream
  • 非流式响应：application/json

1.4 错误响应格式

统一错误包络：

{
  "error": {
    "message": "human readable message",
    "type": "error_type",
    "param": null,
    "code": "error_code"
  }
}
HTTP 状态码 场景
400 请求格式错误、不支持的协议
401 缺少 API Key 或 Key 无效
429 速率限制触发
502 上游厂商返回错误
504 上游厂商超时

2. 核心接口

2.1 POST /v1/chat/completions

OpenAI 兼容的聊天补全接口。这是 MVP 阶段唯一的入站业务接口。

请求体

兼容 OpenAI Chat Completions API。关键字段：

字段 类型 必填 说明
model string 是 平台支持的模型标识
messages array 是 OpenAI 格式的 messages 数组
stream boolean 否 是否使用 SSE 流式响应，默认 false
tools array 否 工具定义数组
temperature float 否 采样温度
max_tokens integer 否 最大生成 token 数
top_p float 否 核采样参数

透传规则：所有非标准字段通过 Envelope.Raw 原样保留，出站时还原为目标厂商格式。

非流式响应（stream=false）

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15,
    "cache_read_tokens": 8,
    "cache_write_tokens": 2
  }
}
  • cache_read_tokens 和 cache_write_tokens 为平台扩展字段（若厂商支持则透传）

流式响应（stream=true）

响应头：

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

响应体格式（SSE）：

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"}}]}

data: [DONE]

中断处理：客户端断开连接时，必须立即向上游传播 context cancel。

2.2 GET /v1/models

返回平台当前支持的模型列表。

响应体

{
  "object": "list",
  "data": [
    {
      "id": "deepseek-chat",
      "object": "model",
      "created": 1710000000,
      "owned_by": "deepseek"
    }
  ]
}

MVP v0.1 模型映射：当前仅支持 deepseek-chat（对应 DeepSeek V3.2）。Anthropic / OpenAI 模型在架构层已预留，接入后自动出现在此列表中。

2.3 GET /health

健康检查端点，无需认证。

响应体

{
  "status": "ok"
}
  • 返回 HTTP 200 表示服务存活

2.4 GET /metrics

Prometheus 指标暴露端点，无需认证。

  • 返回 text/plain 格式的 Prometheus 指标
  • 关键指标参见 modules/system-implementation.md 监控章节

3. 管理接口

MVP 阶段提供基础的管理 API。这些接口同样需要 API Key 认证（建议使用管理员级别的 Key）。

3.1 API Key 管理

POST /admin/api-keys

创建新的 API Key。

请求体：

{
  "name": "my-project-key"
}

响应体：

{
  "id": "uuid",
  "key": "sk-tr-...",
  "name": "my-project-key",
  "key_prefix": "sk-tr-abcd",
  "created_at": "2026-04-16T10:00:00Z"
}

GET /admin/api-keys

列出当前用户的所有 API Keys。

响应体：

{
  "keys": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "name": "my-project-key",
      "key_prefix": "sk-tr-abcd",
      "revoked": false,
      "rate_limit": 60,
      "expires_at": null,
      "created_at": "2026-04-16T10:00:00Z"
    }
  ]
}

key_hash is never returned by the Admin API.

DELETE /admin/api-keys/:id

撤销指定的 API Key。

  • 返回 204 No Content

3.2 用量统计

GET /admin/usage

查询用量统计。

查询参数：

参数 类型 必填 说明
start string (ISO 8601) 否 起始时间
end string (ISO 8601) 否 结束时间
model string 否 按模型过滤
provider string 否 按厂商过滤

响应体：

{
  "period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-16T23:59:59Z"
  },
  "summary": {
    "prompt_tokens": 100000,
    "completion_tokens": 50000,
    "cache_read_tokens": 80000,
    "request_count": 1200,
    "cost_usd": 0.45
  },
  "by_model": [
    {
      "model": "deepseek-chat",
      "prompt_tokens": 60000,
      "completion_tokens": 30000,
      "cost_usd": 0.27
    }
  ]
}

4. Header 约定

Header 用途 示例
Authorization Bearer Token 认证 Bearer tr-test-xxx
Content-Type 请求体格式 application/json
X-Cache-Skip 跳过缓存注入（调试用） true
X-Request-ID 请求追踪 ID uuid

5. OpenAI 兼容性边界

5.1 必须支持的字段

model, messages, stream, tools, temperature, max_tokens, top_p

5.2 透传字段

stop, presence_penalty, frequency_penalty, seed, response_format, logprobs 等所有非标准字段通过 Envelope.Raw 透传。

5.3 不支持的字段（返回 400 或忽略）

  • user（OpenAI 的 end-user 标识）：MVP 阶段可忽略
  • n（生成多少个回复）：MVP 阶段若传入，可返回 400 或固定按 n=1 处理

6. 模型路由映射表

MVP v0.1 的固定模型映射：

模型标识（请求传入） 目标厂商 厂商 Base URL 状态
deepseek-v4-flash DeepSeek https://api.deepseek.com/v1 已接入（主推）
deepseek-v4-pro DeepSeek https://api.deepseek.com/v1 已接入（带 thinking）
deepseek-chat DeepSeek https://api.deepseek.com/v1 已接入（兼容旧名，将于 2026-07-24 弃用）
deepseek-reasoner DeepSeek https://api.deepseek.com/v1 已接入（兼容旧名，将于 2026-07-24 弃用）
claude-sonnet-4-20250514 Anthropic https://api.anthropic.com/v1 预留，Phase 1.1
gpt-4o OpenAI https://api.openai.com/v1 预留，Phase 1.1
gpt-4o-mini OpenAI https://api.openai.com/v1 预留，Phase 1.1