接口总览

AI 模型接口的统一入口地址、认证方式、OpenAI 兼容声明、数据平面与控制平面分界、版本与稳定性承诺，以及一次请求的接口视角时序

本章是天枢智能查询路由聚合平台AI 模型接口的完整参考。您的应用以一套兼容主流大模型协议的接口接入，发起推理查询、获取可调用模型、预先核对用量——平台在背后完成智能研判、择优路由、安全护栏与计量，对您的应用透明。

本页先讲清接口的全局约定：统一入口地址、认证方式、OpenAI 兼容声明、数据平面与控制平面的分界，以及版本与稳定性承诺。各端点的逐字段参考见本章后续分页。

统一入口地址

平台对外暴露两类接口平面，分别对应「发起查询」与「查询管理」两种用途。AI 模型接口属于数据平面：

接口平面	路径前缀	用途	认证方式
数据平面	`/v1/*`	发起推理查询、列模型、预计数，OpenAI 兼容形态	请求头携带 API 密钥（`Authorization: Bearer`）
控制平面	`/api/v1/*`	查询用量、账单、额度，管理密钥等	登录控制台使用

接入推理查询时，您只需关心数据平面 /v1/*。统一入口地址形如 https://<平台入口地址>，请以控制台「账户设置 · 接入参数」中展示的实际地址为准。

统一入口的意义。 您只对接这一个地址，平台在背后完成智能研判、择优路由、安全护栏与计量。背后聚合了哪些模型、如何在模型间切换，对您的应用完全透明——您无需自行对接和维护多家模型。

数据平面所有接口均以 API 密钥鉴权，请在请求头携带：

Authorization: Bearer <您的 API 密钥>

平台数据平面采用 OpenAI 规范兼容 的接口形态。这意味着：

您既有的、基于 OpenAI 协议编写的客户端代码与 SDK，大多可直接复用；
迁移到平台通常只需改动两处——把请求地址（base URL）指向平台统一入口、把密钥换成平台下发的密钥；
请求体与响应体沿用 OpenAI 标准字段（model / messages / stream / max_tokens / temperature 等），无需学习新的字段语义。

base_url  →  https://<平台入口地址>/v1
api_key   →  <您的平台 API 密钥>

平台在 OpenAI 标准结构之上做了向后兼容的扩展：响应的 usage 字段在标准词元计数之外，额外携带本次请求的统一计价词元计量信息（缓存命中、推理档、适用单价档等）。这些扩展字段不影响标准 SDK 的解析，按需读取即可。计量口径详见用量明细与计量说明。

本章覆盖数据平面 /v1/* 下的全部 AI 模型接口：

流式与错误是横切主题。 上述发起查询的接口均支持流式返回，统一的流式形态见流式响应；所有接口共用一套结构化错误体与错误码，见错误码与重试。

请注意两类接口的用途分界，避免混用：

简言之：数据平面只承载「发起一次查询」相关的推理流量；一切「看数据、管配置」的能力都在控制平面。 控制平面接口以登录控制台的会话鉴权，与数据平面的密钥鉴权相互独立。

从您的应用视角看，一次查询经统一入口进入平台，依次经过智能研判、择优路由、安全护栏，再带着计量结果返回：

整个过程对您的应用透明：您只需调用统一入口并携带密钥，平台负责研判、路由、护栏与计量。返回的 usage 中即附本次的统一计价词元用量，可与用量明细的逐条记录复算核对。

项	约定
版本前缀	数据平面统一以 `/v1` 为路径前缀，对齐 OpenAI 协议事实标准
兼容演进	`/v1` 内的字段演进遵循向后兼容原则：新增字段不影响既有调用，已有字段语义不做破坏性变更
不兼容变更	若未来出现不兼容变更，将以新的版本前缀（如 `/v2`）并行提供，并按服务协议约定提前通知，保留迁移窗口
扩展字段	平台在标准结构上扩展的字段（如 `usage` 中的 `price_tier` / `thinking`）按需读取，不读取不影响标准解析
模型名	请求中的 `model` 为平台统一的中性名称；模型清单可能随接入调整而增减，请以模型列表接口实时返回为准

本章中的统一入口地址、模型名均以您控制台「账户设置 · 接入参数」中的实际信息为准；具体单价、信用额度等商务数值不在文档中固化，以服务协议与控制台实时口径为准。