API 参考

灵渠平台数据平面与控制平面的通用接口约定——认证、版本前缀、分页、错误结构与通用查询参数，以及数据/控制两平面端点的总览导航

本节是灵渠平台的接口参考。平台对外暴露两类接口平面：数据平面 承载"发起一次查询"的推理流量，控制平面 承载控制台上"看数据、管配置"的全部管理功能。本页先讲清两平面通用的接口约定（认证、版本、分页、错误、通用查询参数），随后按平面分页给出端点契约。

平面	前缀	用途	主要读者
数据平面	`/v1/*`	兼容主流大模型协议的统一查询入口；客户应用以此发起推理请求	客户应用（API 密钥鉴权）
控制平面	`/api/v1/*`	控制台的查询、统计、配置、对账等全部管理接口	客户 Portal 与运营控制台（会话鉴权）

平面边界。 数据平面只承载"发起一次查询"的推理流量；用量明细、账单、密钥管理、对账等一切"看数据 / 管配置"的能力都在控制平面 /api/v1/*。下文示例中的 https://your-platform 请替换为你的平台实例统一入口地址（可在运营控制台「平台设置 · 接入参数」中查看）。

1. 版本前缀

接口路径中的版本号位于前缀，便于在不破坏既有调用方的前提下演进。

平面	版本前缀	说明
数据平面	`/v1`	对齐 OpenAI 协议事实标准；同时兼容 Anthropic（`/v1/messages`）等主流形态，可直接复用既有 SDK
控制平面	`/api/v1`	资源化 REST 风格；未来出现不兼容变更时升 `/api/v2`，旧前缀保留过渡

2. 认证

两平面采用不同的认证方式，对应两类调用主体。

平面	认证方式	说明
数据平面 `/v1/*`	`Authorization: Bearer <API 密钥>`	客户在控制台申请的子账户密钥（统一 `tsxt-` 前缀）；逐请求鉴权，并归属到对应子账户分账
控制平面 `/api/v1/*`	控制台登录会话	登录后下发会话凭证，随每次请求携带；客户 Portal 与运营控制台共用一套会话机制，视角由平台按账户归属注入

数据平面调用，在请求头携带 API 密钥：

curl https://your-platform/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "Content-Type: application/json" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

控制平面调用，在请求头携带控制台会话凭证（下文示例统一以 Cookie: <控制台会话凭证> 表示，请按你的客户端实际方式携带）：

curl https://your-platform/api/v1/usage/overview \
  -H "Cookie: <控制台会话凭证>"

视角随会话注入。 同一套控制平面接口同时服务客户 Portal 与运营控制台，请求无需声明视角——平台按登录账户归属决定可见的数据范围与口径。运营专属口径（如供应商对账、年度承诺用量进度）只在运营视角返回，客户视角一律不返回该类字段。可随时调用 GET /api/v1/auth/me 核对当前账户与视角。

3. 分页

控制平面的列表类端点统一一组分页参数。

参数	含义	默认
`page`	页码（从 1 起）	1
`page_size`	每页条数	20
`sort_by`	排序字段	按端点默认（多为时间倒序）
`sort_order`	排序方向（`asc` / `desc`）	`desc`

列表响应统一包含 items（数据数组）、total（符合条件的总条数）以及回显的 page / page_size：

{
  "items": [ ... ],
  "total": 0,
  "page": 1,
  "page_size": 20
}

4. 错误结构

接口以统一的错误体返回失败结果，便于调用方本地化处理。

{
  "error": {
    "code": "<字符串错误码，如 quota_exceeded / key_suspended / not_found>",
    "message": "<面向用户的可读说明>",
    "request_id": "<请求追踪标识>"
  }
}

HTTP 状态语义：

状态码	含义
`400`	请求参数错误
`401`	未认证（缺失或无效的密钥 / 会话）
`403`	已认证但无权限
`404`	资源不存在；越权访问对应资源同样返回 `404`，以隔离归属、不泄露资源存在性
`409`	状态冲突（如对已注销的密钥再次操作）
`429`	触发额度暂停或限速
`5xx`	服务端异常

数据平面错误形态。 数据平面 /v1/* 的错误体按其所兼容的协议格式返回（OpenAI 形态的 error 对象），以兼容客户既有 SDK 的错误处理；控制平面统一使用上述 error 结构。

5. 通用查询参数

控制平面的统计 / 明细类端点共享一组时间与维度筛选参数。各端点按需取用其中若干个。

参数	含义
`start` / `end`	统计时间范围（`YYYY-MM-DD`，闭区间）
`granularity`	时间粒度（`hour` / `day` / `week`）
`api_key_id`	按子账户（API 密钥）筛选
`model`	按上游模型筛选（统一中性名）
`billing_month`	结算月（账单 / 对账类，`YYYY-MM`）

例如，按子账户与时间范围、以天为粒度查询用量总览：

curl "https://your-platform/api/v1/usage/overview?start=2026-05-01&end=2026-05-31&granularity=day&api_key_id=<子账户标识>" \
  -H "Cookie: <控制台会话凭证>"

计量与商务口径。 平台以统一计价词元为唯一计量口径，按"输入·缓存命中 / 输入·缓存未命中 / 输出"三类、各分 thinking 与 no-thinking 档，合计六档计量；缓存命中档单价相对更低，thinking（深度推理）档相对溢价。具体单价、信用额度、承诺值等商务数值不在接口契约中固化，以服务协议与控制台实时口径为准；接口只规定口径形态与字段语义。

端点分页导航

按平面分两页给出端点契约：

子页	内容
数据平面	统一查询入口 `POST /v1/chat/completions`、模型列表 `GET /v1/models`、统一计价词元计数 `POST /v1/token-count`——含请求 / 响应 JSON 示例
控制平面	控制台管理接口分组端点表（密钥 / 用量 / 账单 / 额度 / 防护 / 评测 / SLA / 渠道 / 管道 / 微调 / 对账 / 部署 / 数据安全 / 概览 / 会话），每组一张「方法 / 路径 / 用途 / 关键参数」表，重点端点附 JSON 示例

本节定位。 端点契约用于描述接口形态与字段语义，供集成与对接参考。若后续平台实现细节与本文出现偏差，以平台运营控制台「平台设置 · 接入参数」页与各功能页的实际返回为准，本文随之修订。