llm-intelligence/docs/API_REFERENCE.md

API 参考

当前服务端入口位于 cmd/server/main.go，只暴露只读查询接口与健康检查接口。

通用约定

• 基础地址：http://<host>:<port>
• 默认端口：8080
• 返回格式：成功接口统一返回 { "data": ... }
• 失败格式：当前直接返回纯文本错误信息，不是统一 JSON 错误结构
• 鉴权：当前仓库未内建认证、鉴权与限流；公网暴露前应由网关或反向代理补齐

GET /health

检查数据库连通性。

成功

{
  "status": "ok"
}

失败

• 503 database not configured：未配置 DATABASE_URL
• 503 database unavailable：数据库 Ping 失败

示例

curl -fsS http://127.0.0.1:8080/health

GET /api/v1/models

返回模型列表，数据来源于 models、model_provider、region_pricing 当前最新价格快照。

返回体

{
  "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

GET /api/v1/subscription-plans

返回订阅型套餐列表，当前主要对应腾讯云套餐数据。

返回体

{
  "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

GET /api/v1/reports/latest

返回最新“正式日报”元数据。查询条件来自 daily_report：

• status = 'generated'
• output_path 非空
• is_official_daily = true

返回体

{
  "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

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：元数据存在，但落盘文件缺失

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

冒烟检查命令

curl -fsS http://127.0.0.1:8080/health
curl -fsS http://127.0.0.1:8080/api/v1/models | jq '.data | length'
curl -fsS http://127.0.0.1:8080/api/v1/subscription-plans | jq '.data | length'
curl -fsS http://127.0.0.1:8080/api/v1/reports/latest | jq '.data.reportDate'
curl -fsS http://127.0.0.1:8080/api/v1/reports/latest/html > /tmp/latest_report.html

生产暴露建议

• 在 Nginx / 网关上补齐访问控制、速率限制和超时配置
• /health 仅暴露给负载均衡器和监控系统
• 如果前端与 API 同域部署，优先由 Nginx 转发 /api/ 和 /health
• 如果需要公网访问，建议至少加一层 Basic Auth、OIDC 或内网入口限制