231 lines
6.2 KiB
Markdown
231 lines
6.2 KiB
Markdown
# API 参考
|
||
|
||
当前服务端入口位于 `cmd/server/main.go`，只暴露只读查询接口与健康检查接口。
|
||
|
||
## 通用约定
|
||
|
||
- 基础地址：`http://<host>:<port>`
|
||
- 默认端口：`8080`
|
||
- 返回格式：成功接口统一返回 `{ "data": ... }`
|
||
- 失败格式：失败接口统一返回 `{ "error": { "code": "...", "message": "..." } }`
|
||
- 访问控制：`/health` 仅允许本机或私网访问；`/api/*` 对外访问默认要求 `Authorization: Bearer <token>` 或 Basic Auth，详见下文
|
||
- 限流：`/api/*` 默认按来源 IP 做窗口限流；可通过 `API_RATE_LIMIT_PER_WINDOW` 与 `API_RATE_LIMIT_WINDOW_SEC` 调整
|
||
|
||
|
||
## `GET /health`
|
||
|
||
检查数据库连通性。
|
||
|
||
### 成功
|
||
|
||
```json
|
||
{
|
||
"status": "ok"
|
||
}
|
||
```
|
||
|
||
### 失败
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "database_not_configured",
|
||
"message": "database not configured"
|
||
}
|
||
}
|
||
```
|
||
|
||
- `503 database_not_configured`：未配置 `DATABASE_URL`
|
||
- `503 database_unavailable`：数据库 Ping 失败
|
||
### 示例
|
||
|
||
```bash
|
||
curl -fsS http://127.0.0.1:8080/health
|
||
```
|
||
|
||
### 访问控制
|
||
- 仅允许本机或私网请求；外部地址返回 `403 health_endpoint_internal_only`
|
||
|
||
|
||
## `GET /api/v1/models`
|
||
|
||
返回模型列表，数据来源于 `models`、`model_provider`、`region_pricing`；当同一模型存在多条价格记录时，API 按“`global` 区域优先、`official` > `reseller` > `free_tier`、再按 `effective_date`/`id` 倒序”的规则选取主价格。
|
||
|
||
### 返回体
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "openai/gpt-4o",
|
||
"name": "gpt-4o",
|
||
"provider": "OpenAI",
|
||
"providerCN": "OpenAI",
|
||
"modality": "text",
|
||
"contextLength": 128000,
|
||
"pricingMode": "input_output",
|
||
"priceUnit": "million_tokens",
|
||
"inputPrice": 2.5,
|
||
"outputPrice": 10,
|
||
"currency": "USD",
|
||
"isFree": false,
|
||
"stale": false,
|
||
"dataConfidence": "official"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `id` | 模型外部 ID，通常是 `provider/model` |
|
||
| `name` | 模型名称；为空时回退为 `external_id` |
|
||
| `provider` | 英文厂商名 |
|
||
| `providerCN` | 中文厂商名；缺失时回退为英文名或 `external_id` 前缀 |
|
||
| `modality` | 模态类型 |
|
||
| `contextLength` | 上下文窗口 |
|
||
| `pricingMode` | 定价模式：`input_output`（默认，按输入/输出 token）或 `flat`（按字符/秒等单一单位） |
|
||
| `priceUnit` | 价格单位；默认 `million_tokens`，语音类可能是 `10k_characters` / `second` |
|
||
| `flatPrice` | `pricingMode=flat` 时的统一单价 |
|
||
| `inputPrice` | 输入价格，单位与 `currency` 配套，默认按每百万 token |
|
||
| `outputPrice` | 输出价格 |
|
||
| `currency` | 币种 |
|
||
| `isFree` | 是否免费 |
|
||
| `stale` | 是否陈旧数据，当前由 `dataConfidence == "stale"` 推导 |
|
||
| `dataConfidence` | 数据置信度 |
|
||
|
||
### 失败
|
||
|
||
- `503 database_not_configured`
|
||
- `500 query_failed`
|
||
- `401 auth_required`
|
||
- `429 rate_limited`
|
||
|
||
## `GET /api/v1/subscription-plans`
|
||
|
||
返回订阅型套餐列表，当前主要对应腾讯云套餐数据。
|
||
|
||
### 返回体
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"planFamily": "token_plan",
|
||
"planCode": "token-plan-lite",
|
||
"planName": "通用 Token Plan Lite",
|
||
"tier": "Lite",
|
||
"provider": "Tencent",
|
||
"providerCN": "腾讯",
|
||
"operator": "Tencent Cloud",
|
||
"operatorCN": "腾讯云",
|
||
"currency": "CNY",
|
||
"listPrice": 39,
|
||
"priceUnit": "CNY/month",
|
||
"quotaValue": 35000000,
|
||
"quotaUnit": "tokens/month",
|
||
"contextWindow": 0,
|
||
"modelScope": ["tc-code-latest", "glm-5", "glm-5.1"],
|
||
"sourceUrl": "https://cloud.tencent.com/document/product/1823/130060",
|
||
"publishedAt": "2026-04-27T00:00:00",
|
||
"effectiveDate": "2026-04-27"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 失败
|
||
|
||
- `503 database_not_configured`
|
||
- `500 query_failed`
|
||
- `401 auth_required`
|
||
- `429 rate_limited`
|
||
|
||
## `GET /api/v1/reports/latest`
|
||
|
||
返回最新“正式日报”元数据。查询条件来自 `daily_report`：
|
||
|
||
- `status = 'generated'`
|
||
- `output_path` 非空
|
||
- `is_official_daily = true`
|
||
|
||
### 返回体
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"reportDate": "2026-05-13",
|
||
"status": "generated",
|
||
"modelCount": 504,
|
||
"summaryMD": "runtime_audit ...",
|
||
"markdownPath": "reports/daily/daily_report_2026-05-13.md",
|
||
"htmlPath": "reports/daily/html/daily_report_2026-05-13.html",
|
||
"archiveMarkdownPath": "reports/daily/2026/05/daily_report_2026-05-13.md",
|
||
"archiveHtmlPath": "reports/daily/2026/05/daily_report_2026-05-13.html",
|
||
"markdownUrl": "/api/v1/reports/latest/markdown",
|
||
"htmlUrl": "/api/v1/reports/latest/html",
|
||
"updatedAt": "2026-05-13T08:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 失败
|
||
|
||
- `503 database_not_configured`
|
||
- `404 latest_report_not_found`
|
||
- `500 query_failed`
|
||
- `401 auth_required`
|
||
- `429 rate_limited`
|
||
|
||
|
||
## `GET /api/v1/reports/latest/markdown`
|
||
|
||
直接返回最新正式日报的 Markdown 文件内容。
|
||
|
||
### 成功
|
||
|
||
- `200`
|
||
- `Content-Type: text/markdown; charset=utf-8`
|
||
|
||
### 失败
|
||
|
||
- `404 latest_report_not_found`：数据库中没有符合条件的正式日报
|
||
- `404 report_artifact_not_found`：元数据存在，但落盘文件缺失
|
||
- `401 auth_required`
|
||
- `429 rate_limited`
|
||
|
||
## `GET /api/v1/reports/latest/html`
|
||
|
||
直接返回最新正式日报 HTML 文件内容。
|
||
|
||
### 成功
|
||
|
||
- `200`
|
||
- `Content-Type: text/html; charset=utf-8`
|
||
|
||
### 失败
|
||
|
||
- `404 latest_report_not_found`
|
||
- `404 report_artifact_not_found`
|
||
- `401 auth_required`
|
||
- `429 rate_limited`
|
||
|
||
|
||
## 冒烟检查命令
|
||
|
||
```bash
|
||
curl -fsS http://127.0.0.1:8080/health
|
||
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/models | jq '.data | length'
|
||
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/subscription-plans | jq '.data | length'
|
||
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/reports/latest | jq '.data.reportDate'
|
||
curl -fsS -H "Authorization: Bearer $API_AUTH_TOKEN" http://127.0.0.1:8080/api/v1/reports/latest/html > /tmp/latest_report.html
|
||
```
|
||
|
||
|
||
- 在公网暴露时至少配置 `API_AUTH_TOKEN` 或 `API_BASIC_AUTH_USER` / `API_BASIC_AUTH_PASS`
|
||
- `/health` 仅暴露给负载均衡器、监控系统或私网来源
|
||
- 如果前端与 API 同域部署，优先由 Nginx 转发 `/api/` 和 `/health`
|
||
- 如需更强控制，继续在 Nginx / 网关上补齐 CIDR 白名单、OIDC、WAF 与更细粒度限流
|