llm-intelligence/docs/API_REFERENCE.md

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

检查数据库连通性。

成功

{
  "status": "ok"
}

失败

{
  "error": {
    "code": "database_not_configured",
    "message": "database not configured"
  }
}

• 503 database_not_configured：未配置 DATABASE_URL
• 503 database_unavailable：数据库 Ping 失败

示例

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 倒序”的规则选取主价格。

返回体

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

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

返回体

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

返回体

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

冒烟检查命令

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 与更细粒度限流