快速接入指南

本指南帮助您在数分钟内完成接入：从拿到 API 密钥，到发出第一个查询请求并读懂返回的计量信息。整个过程只需要一个统一入口地址、一把密钥，以及您既有的客户端代码。

接入前准备

开始之前，请确认您已具备以下三项：

关于密钥分账。 您可以为不同部门、业务线或成本中心分别申请独立密钥，平台会按密钥自动归属用量、独立分账。密钥的申请、变更与注销详见 API 密钥管理。

统一入口地址

平台对外暴露两类接口，分别对应「发起查询」与「查询管理」两种用途：

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

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

协议兼容性

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

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

以常见的 OpenAI 官方 SDK 为例，迁移通常只是修改初始化时的两个参数：

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

其余调用代码（构造 messages、读取 choices、处理流式分片等）保持不变。

关于模型名。 请求中的 model 字段填写平台模型清单中的模型名。可调用的模型清单可通过数据平面的模型列表接口获取（见下文「查看可调用的模型」），或在控制台查看。模型名为平台统一的中性名称，您无需关心其背后的具体来源。

发出第一个查询

下面是一次最简单的查询调用。把 <平台入口地址> 与 <您的 API 密钥> 替换为实际值即可：

curl https://<平台入口地址>/v1/chat/completions \
  -H "Authorization: Bearer <您的 API 密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型名>",
    "messages": [
      { "role": "system", "content": "你是一名严谨的企业知识助手。" },
      { "role": "user", "content": "请帮我归纳这段会议纪要的三条关键决议。" }
    ],
    "stream": false
  }'

请求成功后，平台返回标准 OpenAI 兼容结构。除生成内容外，usage 字段在标准基础上扩展，携带本次请求的统一计价词元计量信息：

{
  "id": "<响应标识>",
  "object": "chat.completion",
  "created": 0,
  "model": "<本次实际路由的模型名>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "cached_input_tokens": 0,
    "price_tier": "<本次适用单价档>",
    "thinking": false
  }
}

usage 中各字段的含义：

计量口径速读。 平台按「输入·缓存命中 / 输入·缓存未命中 / 输出」三类计量项，各自再分 thinking 与 no-thinking 档，合计 6 档统一计价词元口径。缓存命中档的计价更低，thinking（深度推理）档相对溢价；缓存是否命中以上游模型供应商返回为准。各档计量字段与逐条调用记录的完整说明详见 用量明细与计量说明。

发起流式查询

如需边生成边返回，将请求体中的 stream 设为 true 即可。平台以 OpenAI 兼容的分片（chat.completion.chunk）形态逐段返回，每个分片同样经平台护栏处置后下发：

curl https://<平台入口地址>/v1/chat/completions \
  -H "Authorization: Bearer <您的 API 密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型名>",
    "messages": [
      { "role": "user", "content": "用三句话介绍一下你的能力。" }
    ],
    "stream": true
  }'

查看可调用的模型

发起查询前，您可以先获取当前密钥可调用的模型清单。返回为标准 OpenAI 兼容的模型列表（{ "object": "list", "data": [ { "id": "<模型名>", "object": "model" } ] }）：

curl https://<平台入口地址>/v1/models \
  -H "Authorization: Bearer <您的 API 密钥>"

清单按当前密钥的授权范围过滤，列出的模型名即可直接填入查询请求的 model 字段。

复算核对用量

平台提供统一计价词元的可核验计数接口，便于您对给定文本预先计数、与计费逐条核对：

curl https://<平台入口地址>/v1/token-count \
  -H "Authorization: Bearer <您的 API 密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型名>",
    "messages": [
      { "role": "user", "content": "<待计数文本>" }
    ],
    "thinking": false
  }'

返回按计量档位分列的词元数，可与逐条调用记录中的对应数值复算核对。计数口径与逐条记录的对应关系详见 用量明细与计量说明。

常见接入问题

请求返回 401（未认证）。 多为密钥缺失或格式不正确。请检查请求头是否为 Authorization: Bearer <密钥>，且密钥以 tsxt- 前缀开头、未被注销或暂停。密钥状态可在控制台「API 密钥」页查看。

请求返回 403（无权限）或 404（资源不存在）。 通常为该密钥未被授权调用所请求的模型，或访问了不属于本账户的资源。请确认 model 取自 模型列表接口 返回的清单，并在授权范围内。

请求返回 429（额度暂停或限速）。 表示已触发信用额度暂停或限速。平台采用单层汇总信用额度约束全部密钥，达额时全部密钥一并暂停。额度使用、预警与提额方式详见 额度管理。

响应内容被安全护栏处置。 当请求或响应触发注入防护、敏感信息脱敏或应拒答拦截时，平台会返回结构化的护栏处置结果。护栏能力与误拒说明详见 安全防护。

既有 OpenAI 代码迁移后报错。 优先检查 base URL 是否已指向平台统一入口（需带 /v1）、密钥是否已替换为平台密钥、model 是否填写平台模型名。三处确认无误后，其余调用代码通常无需改动。

错误返回统一采用结构化错误体，包含错误码、可读说明与请求追踪标识，便于您在排查时定位与反馈。

下一步

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