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