# Bridge API 接口文档

这份文档可以直接交给其他 AI，用它为你的程序编写调用代码。下方域名只是示例，请替换成你的网关 HTTPS 域名。

## 快速接入

1. 打开网关的 `/ui`，使用管理员账号密码登录。
2. 在页面的“程序调用 Key”中，为每个程序创建独立的 `gkc_...` **调用 Key**，立即复制保存。完整 Key 只显示一次。
3. 将下列参数交给调用程序：

```text
Base URL: https://gateway.example.com/v1
API Key: 你创建的 gkc_... 调用 Key
Model: 从 GET /v1/models 中选择，例如 openai/实际模型ID、deepseek/实际模型ID
```

管理员密码不能调用 `/v1/*`。所有模型请求都要带 `Authorization: Bearer gkc_...`。不要把调用 Key 写入公开仓库或发给无关人员。

## 接口

| 方法与路径 | 用途 | 鉴权 |
| --- | --- | --- |
| `GET /v1/models` | 返回可选择的模型 ID 列表，形如 `{"object":"list","data":[{"id":"deepseek/...","object":"model"}]}` | 调用 Key |
| `POST /v1/chat/completions` | OpenAI Chat Completions 兼容文本对话 | 调用 Key |
| `POST /v1/responses` | OpenAI Responses 兼容文本对话 | 调用 Key |
| `GET /v1/usage?days=30` | 查看当前调用 Key 最近 1–365 天的用量 | 调用 Key |
| `GET /api-docs.md` | 本文档 | 无 |

模型 ID **必须包含平台前缀**：`openai/`、`qwen/`、`deepseek/`。具体 ID 以 `/v1/models` 为准。模型目录只表示平台报告或管理页配置的模型，实际权限、订阅限制及可用性以请求结果为准。

### Chat Completions

```bash
curl https://gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer gkc_填你的调用Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/实际模型ID","messages":[{"role":"user","content":"你好"}],"stream":false}'
```

必需字段：`model`、`messages`。可选：`stream`，默认 `false`。非流式响应的文本位于 `choices[0].message.content`，用量位于 `usage`（若上游返回）。`stream:true` 返回 `text/event-stream`，逐条 `data: {...}`，末尾 `data: [DONE]`。客户端应按 SSE 处理，不应当作普通 JSON 读取。

在 Windows PowerShell 中可直接测试非流式调用：

```powershell
$headers = @{ Authorization = "Bearer gkc_填你的调用Key" }
$body = @{ model = "deepseek/实际模型ID"; messages = @(@{ role = "user"; content = "你好" }); stream = $false } | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "https://gateway.example.com/v1/chat/completions" -Method Post -Headers $headers -ContentType "application/json" -Body $body
```

### Responses

```bash
curl https://gateway.example.com/v1/responses \
  -H "Authorization: Bearer gkc_填你的调用Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/实际模型ID","input":[{"role":"user","content":"你好"}],"stream":false}'
```

必需字段：`model`、`input`（文本消息数组）。可选：`instructions`、`stream`。非流式文本位于 `output` 数组中 `type:output_text` 的 `text` 字段。`stream:true` 返回 Responses SSE 事件，如 `response.output_text.delta` 和 `response.completed`。

网关会把请求转给该供应商的原生协议；如果入口协议不同，会转换**普通文本对话**。跨协议转换不支持工具调用、图片、音频、JSON schema 和供应商专有参数，遇到不支持的字段会返回 4xx 错误。OpenAI Plus 线路使用授权账号的 Responses 能力，上游固定 `store:false` 且以流式请求；网关可为调用方聚合成非流式响应。`/v1/chat/completions` 是兼容层，并不代表 Plus 账号获得了 OpenAI Platform API 额度。

## Python OpenAI SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.example.com/v1",
    api_key="gkc_填你的调用Key",
)
models = client.models.list()
print([model.id for model in models.data])
result = client.chat.completions.create(
    model="deepseek/实际模型ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(result.choices[0].message.content)
```

给其他 AI 的最短说明：**使用 OpenAI 兼容客户端，Base URL 为 `https://gateway.example.com/v1`，API Key 是管理页单独创建的 `gkc_...`；先请求 `/v1/models` 选择带平台前缀的 ID；文本对话调用 `/v1/chat/completions` 或 `/v1/responses`；支持 `stream`。**

## 用量账本

管理页“用量账本”显示最近 30 天的请求数、输入/输出/总 token，以及按调用 Key、模型、请求的明细。`GET /v1/usage?days=30` 只返回**当前 Key 自己**的记录：

```json
{
  "days": 30,
  "totals": {"requests": 2, "completed": 2, "unreported": 0, "input_tokens": 24, "output_tokens": 12, "total_tokens": 36, "cached_input_tokens": 0, "reasoning_output_tokens": 0},
  "by_key": [], "by_model": [], "by_day": [], "recent": []
}
```

实际返回的数组会包含对应记录。账本只采用上游 `usage`，并记录未上报的请求；未上报不等于 0 token。每个请求有独立 `request_id`，重复写入不会重复计数。请求时间、平台、模型、状态与 token 用量保存在 MySQL；逐请求明细默认保留 90 天，每日汇总持续保留。不记录提示词或完整回复。流式上游若未提供 `usage`，该请求标为“未上报”。这份账本是**用量统计，不是金额账单**。

## 常见错误

| 状态 | 含义 |
| --- | --- |
| `401` | 调用 Key 缺失、错误或已撤销。管理员密码不能用于调用接口。 |
| `400` | JSON、模型 ID、消息格式或跨协议字段不符合网关支持范围。 |
| `502` | 上游连接或响应失败。 |
| 上游原始状态码 | 上游拒绝请求，例如模型无权限、限额耗尽；检查返回的 `error`。 |

接口兼容范围以本文档为准。