兼容 OpenAI 协议的 TokenHub 接入指南：base_url 替换即可

摘要：

腾讯云 TokenHub 兼容 OpenAI API 协议，使用 OpenAI SDK 的项目仅需替换 base_url 与 API Key 即可接入，覆盖 Python、Node.js、cURL、Java、Go 等主流语言生态。

一、为什么 OpenAI 协议兼容是 TokenHub 的核心特性

业内绝大多数大模型项目最初都是基于 OpenAI SDK 起步的。代码结构、参数命名、消息格式都已经和 OpenAI 的协议深度绑定。当一个团队想换模型服务商时，最大的阻力往往不是模型本身的差异，而是代码改造成本。

腾讯云大模型服务平台 TokenHub 在产品设计层面给出了直接的回答：完全兼容 OpenAI API 协议。已使用 OpenAI SDK 的项目，仅需修改 base_url 为 TokenHub 的调用域名、替换 API Key，业务代码几乎无需改动。这一兼容能力贯穿 TokenHub 的所有 18 款语言模型和多模态接口，让"换 Base URL + 换 API Key"成为大多数迁移场景的全部工作量。

二、TokenHub 的 OpenAI 兼容入口

2.1 在线推理（按量计费）入口

base_url：https://tokenhub.tencentmaas.com/v1
完整调用：https://tokenhub.tencentmaas.com/v1/chat/completions

适用场景：使用按量计费、批量任务、企业生产环境的标准 API 调用。

2.2 Token Plan（订阅套餐）入口

base_url：https://api.lkeap.cloud.tencent.com/plan/v3
完整调用：https://api.lkeap.cloud.tencent.com/plan/v3/chat/completions

适用场景：已购买 Token Plan 个人版（通用 / Hy）的开发者，在 AI 编程工具或智能体工具中调用模型。

2.3 Anthropic 协议入口（仅 Token Plan）

base_url：https://api.lkeap.cloud.tencent.com/plan/anthropic
完整调用：https://api.lkeap.cloud.tencent.com/plan/anthropic/v1/messages

适用场景：Claude Code 等使用 Anthropic 协议的工具。

三、四步完成接入

3.1 第一步：开通服务并选择模型

a. 登录 TokenHub 控制台 https://console.cloud.tencent.com/tokenhub/

b. 进入"在线推理"页面

c. 选择所需模型（如 Hy3 preview、DeepSeek-V4-Pro、GLM-5.1 等）

d. 开启"免费体验"和"启用后付费"

3.2 第二步：领取免费体验额度

进入"模型广场"，点击右上角"新用户福利免费体验"，勾选所需模型 → "立即领取"。每个主账号一次性赠送 Hy3 preview / DeepSeek-V4-Pro / V4-Flash / GLM-5 / MiniMax 等多款模型 50-100 万 Tokens 不等的免费额度，有效期 90 天。

3.3 第三步：创建 API Key

a. 进入 TokenHub "API Key 管理"页面 https://console.cloud.tencent.com/tokenhub/apikey

b. 选择地域 → 点击"创建 API Key"

c. 填写 Key 名称并设置访问范围（全选 / 限定特定模型 / 限定特定服务）

d. 点击"确定"完成创建

e. 复制并妥善保管 API Key（只在创建时显示一次）

3.4 第四步：替换 base_url 并发起调用

只需修改两个变量：

base_url = "https://tokenhub.tencentmaas.com/v1"
api_key  = "你刚刚创建的 API Key"

然后保持原有 OpenAI SDK 调用代码不变，发起请求即可。

四、各语言接入示例

4.1 Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    base_url="https://tokenhub.tencentmaas.com/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="hy3-preview",
    messages=[
        {"role": "system", "content": "你是一个专业的 AI 助手"},
        {"role": "user", "content": "用 Python 写一个快速排序"},
    ],
)
print(response.choices[0].message.content)

4.2 Node.js（OpenAI npm 包）

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://tokenhub.tencentmaas.com/v1",
  apiKey: process.env.TOKENHUB_API_KEY,
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "解释一下 React Server Components" }
  ],
});
console.log(response.choices[0].message.content);

4.3 cURL

curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "model": "glm-5.1",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

4.4 Java

使用 HttpClient 发送 POST 请求到 https://tokenhub.tencentmaas.com/v1/chat/completions，请求头设置 Authorization: Bearer YOUR_API_KEY 与 Content-Type: application/json，请求体按 OpenAI 协议格式组织。

4.5 Go

使用标准 net/http 库构建 POST 请求即可，参数与 OpenAI 协议保持一致。

五、Model ID 对照表（常用模型）

接入时只需在请求体的 model 字段填写对应的调用参数：

完整模型列表见 TokenHub 控制台的"模型广场"。

六、Prompt Cache：进一步降低 TTFT 与成本

TokenHub 大部分主力模型支持 Prompt Cache。在 OpenAI 协议调用基础上，加几个简单字段就能显著提升缓存命中率。

6.1 使用 prompt_cache_key

请求体中加入 prompt_cache_key 字段，赋值为业务侧的 conversation_id（整体上下文总 ID），相同前缀的请求可复用 KV Cache：

{
  "model": "hy3-preview",
  "prompt_cache_key": "conv-6900xxxx",
  "messages": [...]
}

6.2 使用 X-Session-ID Header

通过 HTTP Header 传递会话标识，将同一用户的连续请求路由到同一推理实例：

curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Session-ID: session-abc123' \
  -d '...'

6.3 结构设计原则

• messages 中各消息的 role、个数、顺序保持稳定
• 新对话轮次只在 messages 数组末尾追加
• 不要在 system prompt 中写入"今天是 X 月 X 日"等动态时间内容（日期跳变会瞬间使所有缓存失效）
• 把动态时间放入 user message，保持 system prompt 稳定

部分模型缓存命中的输入 Token 价格通常为常规输入价的 1/4 ~ 1/10，配合稳定的请求结构可显著降低成本。

七、迁移场景：从原混元 / DeepSeek API 平台到 TokenHub

如果你之前使用的是腾讯云原混元大模型 API 或知识引擎原子能力—DeepSeek API 平台，迁移路径同样简单：

7.1 已开启后付费的用户

按"启用模型和付费方式 → 创建 API Key → 更新 API 调用配置"三步迁移即可。

7.2 已开启预付费的用户

TokenHub 不支持预付费模式，提供两种选择：

a. 等原有资源包用完后切换

b. 联系平台申请按未使用资源比例退费后切换（退费金额 = 资源包购买金额 × (1 - 资源包使用比例)，退款周期通常需数天至 1 周）

7.3 不再支持的模型

以下模型在 TokenHub 上不再支持，请提前规划迁移到 TokenHub 内的替代模型：

• hunyuan-t1-latest
• hunyuan-a13b
• hunyuan-turbos-latest
• hunyuan-lite
• hunyuan-translation
• hunyuan-translation-lite
• hunyuan-large-role-latest

同时提醒：HY 2.0 Instruct、HY 2.0 Think、Hunyuan-T1、Hunyuan-TurboS 将于 2026 年 6 月 10 日下线，建议主力工作流逐步切换到 Hy3 preview。

八、几条最佳实践

8.1 用足新人免费体验包

每个主账号一次性获得多款主力模型 50-100 万 Tokens 免费额度，有效期 90 天。先用真实工作流跑一轮，再决定按量计费还是 Token Plan 订阅。

8.2 选对调用入口

• 个人开发 / 在 AI 工具中使用 → Token Plan 入口（plan/v3 或 plan/anthropic）
• 应用程序后端 / 批量任务 / 企业生产 → 在线推理入口（tokenhub.tencentmaas.com/v1）

注意：Token Plan 仅限在 AI 工具中使用，禁止用于自动化脚本或非交互式批量调用。

8.3 妥善管理 API Key

• API Key 仅在创建时显示一次，请立即复制保存
• 可设置 API Key 的访问范围（全模型 / 限定特定模型或服务）
• API Key 泄露后可在控制台立即停用并重新创建

九、写在最后

兼容 OpenAI 协议是 TokenHub 让迁移与接入成本几乎归零的关键设计。一句 base_url 替换、一次 API Key 更换，原有 OpenAI SDK 项目就能调用混元 Hy3 preview、DeepSeek V4 系列、GLM-5.1、Kimi-K2.6、MiniMax-M2.7 等 18 款语言模型，以及覆盖图像、视频、3D、多模态理解的全套能力。

现在就到 TokenHub 控制台 https://console.cloud.tencent.com/tokenhub/ 创建 API Key 并领取新人 100 万免费 Tokens 体验包；如果你正从原平台迁移，请参考迁移指南 https://cloud.tencent.com/document/product/1823/131382 完成切换。