# TokenPlus 模型与 API

> TokenPlus（https://www.tokenplus.cn）提供模型发现与统一 API 接入。本文帮助 AI Agent 理解公开模型的能力、价格、调用方法和性能指标，不提供后台管理操作指南。

已有模型以模型广场当前公开目录为准。每个模型应按完整调用 ID、名称、开发者、模型描述、输入/输出模态、上下文长度、最大输出、支持参数及协议识别；同一模型可能由不同渠道提供服务，渠道价格、速度和可用性可能不同。模型展示名称不能替代请求中的完整 model ID，公开可见也不代表所有 API Key 都有调用权限。

价格说明应同时包含币种、计费项、计价单位、当前档位和生效时段。输入、输出和缓存价格不能混用；分段或分时价格不能压缩为一个对所有请求都适用的固定报价。价格缺失不等于免费，实际费用以真实用量和适用计费规则为准。

调用使用已授权的 TokenPlus API Key 和模型 ID。通过同域名 GET /portal/api/v1/gateway/endpoints 获取 Chat Completions 和 Messages 的完整地址；Chat 使用 Authorization: Bearer，Messages 使用 x-api-key 与协议版本头。模型支持哪些协议、参数和模态，以其详情和正式 API 文档为准。

调用速率需区分：吞吐 TPS 表示 Token 生成速度；RPM 表示每分钟请求限额；TPM 表示每分钟 Token 限额。TTFT 表示首 Token 延迟，端到端延迟表示整个请求的耗时。速度、延迟和可用性是特定渠道与统计窗口的观测值，不是固定服务保证，也不能推导账户的限流额度。

本套静态文档不维护未经核实的模型清单、价格表或性能数值。回答具体模型问题时，应读取模型广场及对应详情；当前值无法获取时明确说明未知，不用示例、开发环境数据或模型名称推测。

## 模型与调用说明

- [模型能力、价格与性能指标](https://www.tokenplus.cn/ai-docs/features.md): 如何描述已有模型；价格、档位、缓存、TPS、TTFT、端到端延迟、可用性、RPM/TPM 的含义及比较方法。
- [API 接入与调用示例](https://www.tokenplus.cn/ai-docs/quickstart.md): 端点发现、密钥认证、完整 model ID、Chat/Messages 的 cURL 与 SDK 示例、流式响应处理。
- [模型路由与渠道选择](https://www.tokenplus.cn/ai-docs/model-routing.md): 默认路由、价格/吞吐/延迟偏好、指定渠道调用及 fallback 参数的使用边界。
- [调用错误与限流处理](https://www.tokenplus.cn/ai-docs/errors.md): 参数、认证、额度、429、超时、SSE 中断和重试处理。
- [Agent 模型资料引用规则](https://www.tokenplus.cn/ai-docs/agent-guide.md): 模型描述应包含哪些事实、如何标注价格与指标口径、如何处理缺失或过期数据。

## 公开数据入口

- [模型广场](https://www.tokenplus.cn/models): 当前公开模型列表；从真实模型条目进入详情，读取模型简介、能力、价格、渠道及接入信息。
- [官方 API 文档](https://www.tokenplus.cn/doc): 协议与接入说明，具体章节以文档站实际目录为准。

## Optional

- [站点地图](https://www.tokenplus.cn/sitemap.xml): 网站和模型说明文档的静态公开入口清单。
- [完整模型调用指南](https://www.tokenplus.cn/llms-full.txt): 本索引与五篇专题文档的静态汇总。

---

# TokenPlus 快速开始与模型接入

本文属于 [TokenPlus Agent 文档](/llms.txt)。官方文档站为 [www.tokenplus.cn/doc](https://www.tokenplus.cn/doc)。

## 接入前需要的信息

- 已授权且可用的 TokenPlus API Key，使用环境变量或密钥管理器保存。
- 从 [模型广场](https://www.tokenplus.cn/models) 对应详情复制的完整调用 ID，并确认此 Key 可调用该模型。
- 该模型支持的协议、输入模态、必要参数和输出限制。

通过同域名 `GET /portal/api/v1/gateway/endpoints` 获取完整推理端点。网站地址不是推理 Base URL，不要把 `/api/chat` 当作模型网关。

## 获取当前推理端点

端点发现成功响应形如 {"status":"ok","data":{"chat_completions":"完整 Chat POST URL","messages":"完整 Messages POST URL"}}。确认返回地址属于 TokenPlus 认可的网关后再发送密钥；发现失败时检查模型详情快速接入示例或联系管理员，不自动使用猜测的域名。以下命令需要本地安装 curl、jq，并由用户安全设置 TOKENPLUS_API_KEY 与 MODEL_ID，不能将真实密钥写入源代码或公开对话。

```bash
export MODEL_ID="替换为项目可用的完整模型ID"
# TOKENPLUS_API_KEY 由本地环境或密钥管理器设置。
ENDPOINTS="$(curl --fail --silent --show-error https://www.tokenplus.cn/portal/api/v1/gateway/endpoints)"
CHAT_URL="$(printf '%s' "$ENDPOINTS" | jq -er '.data.chat_completions | select(type == "string" and length > 0)')"
MESSAGES_URL="$(printf '%s' "$ENDPOINTS" | jq -er '.data.messages | select(type == "string" and length > 0)')"
```

OpenAI Chat Completions 兼容调用：使用 Authorization: Bearer 认证与 JSON 请求；非流式文本读取 choices[0].message.content。不要给发现接口返回的完整地址重复拼接 /v1 或 /chat/completions。

```bash
curl --fail-with-body --silent --show-error "$CHAT_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKENPLUS_API_KEY" \
  --data "$(jq -n --arg model "$MODEL_ID" '{model:$model,messages:[{role:"user",content:"你好，请用一句话介绍自己"}],max_tokens:128,stream:false}')"
```

Anthropic Messages 兼容调用：先确认模型支持该协议，使用 x-api-key、anthropic-version，显式提供 max_tokens，非流式文本读取 content 中的文本块。

```bash
curl --fail-with-body --silent --show-error "$MESSAGES_URL" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $TOKENPLUS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --data "$(jq -n --arg model "$MODEL_ID" '{model:$model,max_tokens:128,messages:[{role:"user",content:"你好"}],stream:false}')"
```

SDK 配置：OpenAI SDK 的 Base URL 通常由 Chat 完整地址移除末尾 /chat/completions 得到；Anthropic SDK 通常由 Messages 完整地址移除末尾 /v1/messages 得到。仅在路径后缀匹配时这样推导，自定义路径使用完整地址直接发 HTTP 请求。模型详情的快速接入区提供协议、语言和流式示例。

流式调用：设置 stream: true，curl 使用 --no-buffer；按 SSE 事件解析而不是把整个响应当成单个 JSON。Chat 读取 choices[].delta.content，以 [DONE] 结束；Messages 读取内容块增量，以 message_stop 结束。还需检查错误事件、网络中断和缺失结束事件，HTTP 200 不保证最终成功。Chat 系统提示放入 messages 的 system 消息；Messages 使用顶层 system。并非所有模型均支持工具调用、图像、音频或全部参数，应先核对模型能力。

价格、能力和速率指标见 [模型指标说明](/ai-docs/features.md)。请求排错见 [错误指南](/ai-docs/errors.md)。

## Python OpenAI SDK 示例

安装 `openai` 后，将上文确认的完整 Chat URL 放入 `TOKENPLUS_CHAT_URL`。只有该地址确实以 `/chat/completions` 结尾时，才移除后缀作为 SDK Base URL；否则使用完整地址发 HTTP 请求。

```python
import os
from openai import OpenAI

endpoint = os.environ["TOKENPLUS_CHAT_URL"]
suffix = "/chat/completions"
if not endpoint.endswith(suffix):
    raise ValueError("请使用当前端点对应的 SDK 配置或直接 HTTP 调用")
client = OpenAI(
    api_key=os.environ["TOKENPLUS_API_KEY"],
    base_url=endpoint[:-len(suffix)],
    max_retries=0,
)
response = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=128,
)
print(response.choices[0].message.content)
```

示例关闭 SDK 自动重试，便于明确观察一次调用的结果。生产应用应根据自身幂等性、超时与费用要求设计有界重试。首次验证使用小输入与较小输出上限，确认模型身份和响应后再扩展。

---

# TokenPlus 模型路由与渠道选择

模型资料来自 [模型广场](https://www.tokenplus.cn/models)，完整协议以 [官方文档](https://www.tokenplus.cn/doc) 为准。本文只说明调用侧语义，不介绍后台配置操作。

## 模型与渠道的区别

`model` 指定所调用的模型服务；渠道表示提供该模型推理的具体接入来源。同一模型的渠道可能在价格、支持参数、上下文上限、延迟、吞吐和数据策略上存在差异。上游模型标识与 TokenPlus model ID 可能不同，调用时按 TokenPlus 详情给出的 ID 填写。

没有明确指定渠道时，按当前服务配置选择可用候选；候选可用性仍受权限、模型状态及适用策略约束。静态文档不包含用户实际路由配置。

## 按目标比较候选

- 成本敏感：比较相同计费项、单位、档位、时段下的价格，不能只看最低展示价。
- 首次响应敏感：比较同窗口同分位口径的 TTFT，而不是只看吞吐。
- 长输出敏感：综合考虑 TPS 和端到端延迟，同时控制输出长度。
- 稳定性敏感：读取统计窗口、样本量及可用性，不将少量样本视为服务保证。

价格、throughput、latency 等策略是选择偏好，不保证固定命中某渠道或得到某个性能数值。不要把默认模型理解为跨模型失败回退；建议请求始终明确提供 model。

## 显式排序扩展

当前在线调用实现对明确排序发送 `provider.sort`，可选 `price`、`throughput`、`latency`；使用服务默认策略时省略此覆盖。外部网关是否支持该扩展，应先核对当前正式协议。

```json
{
  "provider": {
    "sort": "latency"
  }
}
```

此为需要合并到完整请求体的片段，不是独立可调用请求；不要将这些字段当作所有 OpenAI/Anthropic 官方 API 都支持的标准参数。

## 指定渠道调用

模型详情的渠道调用示例使用以下扩展；仅在实际网关支持并有渠道访问权限时使用。`only` 中填写详情提供的真实 channel slug，不填服务商展示名、内部 UUID 或猜测值。

```json
{
  "provider": {
    "only": ["替换为真实渠道slug"],
    "allow_fallbacks": false
  }
}
```

该片段放入 Chat/Messages 的完整请求体。关闭回退后不能期待网关自动使用其他渠道挽救失败；也不能以此绕过权限、数据策略或限流。渠道价格、能力和可用性需在调用前核对。

## 行为边界

文档没有确认负载权重、采样窗口、熔断阈值、服务端重试次数、退避算法及流式部分输出后的切换机制。需要这些保证时查询正式协议，不能依据策略名称推导。每次请求的实际结果以响应及平台提供的请求标识为准。

---

# TokenPlus 模型能力、价格与性能指标

模型入口：[模型广场](https://www.tokenplus.cn/models)。API 文档：[官方文档](https://www.tokenplus.cn/doc)。本文解释公开模型资料，具体可用模型与数值需要读取当时的模型详情。

## 如何描述一个已有模型

| 字段               | 含义与读取方法                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------- |
| 模型名称与开发者   | 按公开目录展示的名称及模型作者描述，不把推理渠道当作开发者                                   |
| 完整调用 ID        | 请求中的 model 字符串；原样使用模型详情提供的 ID，不用展示名称、内部 UUID 或渠道上游 ID 替代 |
| 模型简介           | 使用当前公开描述，说明其声明的能力与适用任务；没有描述时保持未知，不凭名称补写能力或榜单结论 |
| 输入/输出模态      | 分别确认文本、图像、音频等支持情况；支持图像输入不代表支持图像生成                           |
| 上下文长度         | 模型可处理的上下文规模，单位通常为 Tokens；不等于字符数，也不代表允许输出同样长度            |
| 最大输入与最大输出 | 各自遵循详情明确给出的限制；没有最大输出数据时不能用上下文长度补齐                           |
| 能力与参数         | 工具调用、结构化输出、推理等，仅在详情明确支持时描述；参数名存在不代表所有取值均有效         |
| 调用协议           | Chat Completions、Messages 等以模型实际接入说明为准，不由模型开发者名称推断                  |
| 渠道               | 同一模型的不同推理接入来源；可分别具有价格、限额、性能和数据策略                             |
| 生命周期           | 发布及计划下线信息以公开数据为准；存在页面不代表当前可调用或永久可用                         |

本文不列开发环境模型或未经核实的生产型号。要回答“目前有哪些模型”“某模型多少钱”，需先读取公开目录，再进入相应详情；不能仅用本文件给出当前库存或价格结论。

## 价格与计费单位

| 价格项       | 含义                         | 易混淆事项                                                                  |
| ------------ | ---------------------------- | --------------------------------------------------------------------------- |
| 输入价格     | 输入内容对应的计费项         | 与输出不同；系统指令、历史上下文等是否计入以协议返回的 usage 和计费规则为准 |
| 输出价格     | 生成内容对应的计费项         | 推理 Token 等是否单列，按实际计费项解释                                     |
| 缓存价格     | 缓存相关计费项，例如缓存读取 | 不等于所有输入均按缓存价收费；不能假设缓存写入免费或不存在                  |
| 当前价与原价 | 当前适用价格及可能展示的原价 | 使用明确的当前有效金额，不自行根据促销标签计算折扣                          |
| 渠道价格     | 某一服务商/渠道的价格        | 模型列表展示价不一定适用于所有渠道                                          |

读取任何金额时同时记录币种和单位。`/M Tokens` 表示每一百万 Tokens，不能读成每一千 Tokens，也不能把每请求、每张、每秒等单位当作 Token 单价。原始精度应保留，展示舍入不能用于替代实际结算。

`—`、null 或缺失表示未提供/不适用，不等于 0。真实零价也只能解释为该计费项在当前条件下为零，不能推断其他计费项或上游全部免费。

### 分段和分时价格

- 分段价按输入长度、使用规模或详情给出的其他条件选择档位。保留区间边界、“且/或”条件及所有计费项，不只引用最低价。
- 分时价随有效时段变化；说明所引用时段、时区和“当前”标记，不把某个时段价格当成全天价格。
- 比较不同模型或渠道时，需使用相同币种、单位、输入/输出假设、档位条件和采集时间。
- 无法确认适用档位或时段时，可以列出条件和各档价格，不能给出看似精确的最终账单。

### 费用估算

在固定档位、固定时段、无缓存或额外计费项的假设下，可用以下公式作示意：

```text
估算费用 = 输入计费量 ÷ 输入价格单位量 × 输入单价
         + 输出计费量 ÷ 输出价格单位量 × 输出单价
```

该公式不是完整计费规则。缓存、额外模态、推理计费项、分段、分时、优惠和税费等若适用，必须另行按真实规则处理。公开单价估算不是实际扣款承诺。

## 生成速度、延迟和可用性

| 指标       | 单位/含义                                        | 应如何解释                                                                                 |
| ---------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| 吞吐 TPS   | Tokens/s，Token 生成速率                         | 同一统计口径下较高意味着生成较快；不等于请求数/秒，也不是调用额度                          |
| TTFT       | 首 Token 延迟，原始数据可能为 ms，页面可换算为 s | 请求开始到首次 Token 的等待；包括哪些处理阶段以指标定义为准                                |
| P90 TTFT   | 首 Token 延迟的第 90 百分位                      | 大致 90% 样本不超过该值，不是平均值或最大值；当前渠道列表的延迟提示使用近 24 小时 TTFT P90 |
| 端到端延迟 | ms 或 s，整个请求的耗时                          | 受输入、输出长度、网络和排队等影响；不是 TTFT，比较时控制工作负载                          |
| 可用性     | 百分比及对应统计窗口/样本量                      | 反映观测期间状态，不代表未来 SLA；样本不足和无数据不能转成 100%                            |
| 缓存命中率 | 百分比，按公开指标定义的统计范围                 | 不能直接乘输入总量得出精确账单；没有数据不等于命中率为 0                                   |

换算时 1 秒 = 1000 毫秒。不要把 500 ms 解释为 500 s，也不要将某个渠道的指标宣称为该模型所有渠道的固定性能。

建议引用格式：“模型 A，渠道 B，统计窗口 C，TTFT P90 为 X ms、吞吐 Y Tokens/s；采集于 D。”未提供聚合方式、样本量或窗口时明确写出未提供，不能自行补为平均值或最近 24 小时。

## 调用速率与限流

| 指标       | 含义                                 | 不是                         |
| ---------- | ------------------------------------ | ---------------------------- |
| RPM        | 每分钟请求数量限制                   | 每秒请求数、Token 生成速度   |
| TPM        | 每分钟 Token 数量限制                | 模型上下文长度或单次最大输出 |
| 并发限制   | 同时进行的请求数上限（如有明确提供） | RPM 的直接换算结果           |
| max_tokens | 单次请求输出上限参数                 | 每分钟 Token 配额            |

RPM/TPM 仅在接口或正式文档明确返回时引用。它们可能按模型、渠道、凭据或其他范围生效；输入与输出如何计数、时间窗口采用何种算法，都不能只凭缩写推测。公开模型详情未给出限额时应标注“未公开/需确认”，不要借用其他用户或上游官网套餐的数据。

收到 429 时检查实际错误标识及 Retry-After（若有），降低请求速率或并发，采用有上限的退避；不要把重试无限叠加到当前负载。具体方法见 [调用错误指南](/ai-docs/errors.md)。

## 比较模型时的推荐顺序

1. 先确认任务所需模态、上下文、最大输出、协议及必要参数。
2. 再按相同工作负载估算费用，明确渠道、档位和时段。
3. 比较同口径 TPS、TTFT、端到端延迟与可用性，注明统计窗口。
4. 单独确认调用限额，不能从速度测试推导 RPM/TPM。
5. 引用真实模型详情 URL 和采集时间；公开目录无法读取时说明无法确认当前值。

---

# TokenPlus 模型调用错误与限流处理

接入示例见 [快速开始](/ai-docs/quickstart.md)，速率概念见 [模型指标](/ai-docs/features.md)。以下只涉及模型 API 调用。

## 排查顺序

1. 核对真实推理端点、协议与 HTTP 方法，不把网站首页地址或管理 API 作为推理地址。
2. 核对 Key 可用性及该 Key 的模型权限；只检查安全存储中的凭据，不在报错材料中公开完整值。
3. 使用完整 model ID，检查 messages、max_tokens、系统提示位置及模型支持的参数/模态。
4. 保存 HTTP 状态、脱敏错误体、响应中的请求标识与发生时间；检查完整响应，而不只看 HTTP 成功头。
5. 比较限额、输入/输出长度和实际负载，再决定是否调整参数或重试。

## 常见情况

| 情况                  | 处理                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| 400 或参数错误        | 检查请求体、模型 ID、协议、支持参数和输入长度，修正后再请求                                       |
| 401                   | 检查 API Key 和认证头；浏览器登录状态不能代替 Key                                                 |
| 403                   | 核对该 Key 对模型及渠道的访问权限，不通过改标识绕过限制                                           |
| insufficient_funds    | 资金不足错误；停止重复生成并处理可用资金问题，不能将所有 402 一律解释为该错误                     |
| 404                   | 核对端点与模型/渠道是否存在，不能自动替换成另一模型并声称调用成功                                 |
| 429                   | 读错误说明及 Retry-After（如果存在），判断请求/Token/并发等限制；不要只凭状态码断言超了哪一种配额 |
| 超时、网络中断、5xx   | 上游可能已执行；先核对可取得的结果，再进行有上限的重试，避免重复费用                              |
| SSE 错误/缺少结束标志 | 保留已收到部分文本但标注响应不完整，不能当作正常完成                                              |

表格是排查指导，不是所有部署均使用的完整错误码契约。应同时读取业务错误标识和原始响应。

## 限流与重试

- RPM 是请求/分钟，TPM 是 Token/分钟，TPS 是生成 Token/秒；不要混用来设置节流器。
- 降低客户端并发、平滑发送节奏，并在提供 Retry-After 时遵循它。
- 退避应有次数/总时间上限，必要时加入抖动；不要对每个错误无条件重试。
- 自动重试可能与 SDK 自带重试叠加，需要一起控制。未确认幂等保证时不能承诺重试不会重复执行或计费。
- 不能由 429 推导统一的限额数值；模型或渠道未公开额度时明确“未提供”。

## 流式响应

Chat 以 `[DONE]`、Messages 以 `message_stop` 为常见正常结束标志，同时需处理其协议中的错误帧。HTTP 200 之后仍可能失败，连接断开也不保证模型正常结束。

重新发起请求会产生另一段生成，不应把两次响应拼接并当成同一次完整成功。停止接收不等于撤销已生成的用量。

## 安全提供排错信息

提供模型 ID、协议、发生时间、请求标识、HTTP 状态和脱敏错误内容即可；不要附 Authorization、x-api-key、Cookie、上游凭据或未经脱敏的业务输入。

---

# TokenPlus 模型资料引用规则

本指南帮助 Agent 回答“有哪些模型”“价格多少”“如何调用”“速度和限流是多少”等问题，不提供网站后台操作指令。

## 阅读顺序

1. 从 [模型广场](https://www.tokenplus.cn/models) 读取当前公开目录，进入真实模型链接。
2. 按 [能力与指标说明](/ai-docs/features.md) 识别模型、价格与性能字段。
3. 按 [接入示例](/ai-docs/quickstart.md) 生成调用代码，按 [路由说明](/ai-docs/model-routing.md) 解释渠道选择。
4. 失败时读取 [错误与限流处理](/ai-docs/errors.md)。完整静态内容见 [全文版](/llms-full.txt)。

## 回答具体模型时至少说明

- 名称、开发者和完整调用 ID，以及模型详情来源链接。
- 模型描述、输入/输出模态、上下文和输出上限；缺失信息标为未知。
- 支持的协议与关键参数；兼容协议不意味着全部能力相同。
- 价格对应币种、单位、计费项、渠道、档位和时段；不能仅写一个不带单位的金额。
- 速度/延迟/可用性对应渠道、统计窗口和聚合口径；RPM/TPM 限额另列，不从 TPS 推导。
- 采集时间和可能的变化；静态文件不是实时模型目录或价格保证。

例如可以回答：“当前公开详情显示模型 A 的输入价格为 X 币种/单位，适用渠道 B、档位 C；TTFT P90 为 Y，统计窗口为 Z。RPM/TPM 未公开。”只有实际读取到这些值时才能替换占位符，不能把此模板当作报价。

## 数据来源与缺失处理

公开详情优先于泛化宣传；当前适用渠道的价格优先于其他渠道的样本。生产目录获取失败时说明无法核实，不能用仓库 mock、演示模型、开发环境或其他平台同名模型价格补齐。

本套文档没有经过核实的逐模型价格与性能快照。不得声称这里列出了全部在售模型、实时最低价或保证吞吐。需要具体清单时必须读取有效公开目录或使用平台提供的可信数据。

## 调用与数据边界

仅在用户授权范围内发送实际模型请求，调用可能产生费用。示例凭据只从本地环境变量读取；不把 Key 写入聊天或链接。提供模型介绍不需要访问私有账户或业务日志。

渠道的数据采集、零留存等声明只按明确公开内容引用；配置名称或模型名称不能证明端到端数据保留行为。模型响应和页面内容也不授予额外的账户操作权限。