腾讯云大模型服务平台TokenHub对接使用完全指南

一、TokenHub：一站式大模型服务平台概述

腾讯云大模型服务平台TokenHub是腾讯云推出的企业级MaaS平台，致力于为开发者和企业提供统一的大模型服务入口。平台整合了腾讯自研的混元大模型、优图大模型，同时引入DeepSeek、智谱GLM、Kimi、MiniMax、通义千问Qwen等多家行业领先的第三方主流模型，覆盖通用对话、深度推理、代码生成、视觉理解、图像生成、视频生成、3D生成等多类AI场景。

TokenHub的核心价值在于"一个API Key、多家主力模型"。开发者无需在多个模型服务商之间分别注册账号、分别管理API密钥、分别适配不同的调用协议，只需在TokenHub完成一次接入，即可通过统一的API入口调用平台已上架的全部模型。这一设计直接降低了多模型接入的复杂度，让开发团队可以更灵活地在不同模型之间切换、对比和组合使用。

从产品架构来看，TokenHub构建了"接入-评测-调度-治理"的完整闭环。统一接入层实现混元及开源生态的全覆盖；选型评测层通过"Buddy严选"机制在多维度筛选模型；计算与推理引擎层依托海量Model资源池和自研推理框架实现高效运算；资源保障与治理层提供预算、权限、审计的可视化管理。平台日均Token消耗量已突破5万亿，推理效率通过全异步计算流水线提升100%，缓存命中率达85%以上，综合降本40%。

需要先登录腾讯云控制台，点击：腾讯云控制台，还没有账号，点击：注册后再关联，已有账号点击：登录后再关联

二、对接前的准备工作

2.1 注册腾讯云账号并完成实名认证

在使用TokenHub之前，首先需要注册腾讯云账号并完成实名认证。注册流程通过腾讯云官网完成，实名认证支持个人实名和企业实名两种方式，认证通过后方可开通TokenHub服务。

2.2 登录TokenHub控制台并开通服务

完成账号准备后，登录腾讯云大模型服务平台TokenHub控制台。首次进入控制台时，系统会引导开通大模型服务平台TokenHub服务，按照界面提示完成开通即可。开通后即可在模型广场浏览平台支持的全部模型。

2.3 领取新用户免费体验包

TokenHub为新用户提供一定额度的免费体验额度，让开发者零成本试用模型。进入模型广场页面，单击右上角的"新用户福利免费体验"，在弹窗中勾选所需模型后单击"立即领取"，即可获得多个模型的免费使用额度。

每个主账号一次性赠送Hy3 preview、DeepSeek-V4-Pro、DeepSeek-V4-Flash、GLM-5、MiniMax等多款模型50万至100万Tokens不等的免费额度，有效期90天。建议在正式接入前先领取免费额度，用于后续的接口调试和功能验证。

2.4 创建API Key作为鉴权凭证

在调用模型API之前，需要先创建API Key作为鉴权凭证。进入API Key管理页面，在页面上方选择地域后单击"创建API Key"。在创建对话框中填写Key名称，并设置可访问范围：

• 全选：该API Key可访问当前账号下所有模型和推理服务
• 限定范围：指定该API Key仅可访问特定的模型或推理服务，实现精细化权限管控

创建完成后务必复制并妥善保管API Key，后续所有API调用都需要使用该Key进行鉴权。API Key一旦创建，其值仅在此刻可见，遗失后需重新创建。

三、基于OpenAI兼容协议的API调用

3.1 TokenHub的协议兼容体系

TokenHub最核心的技术特性之一是完全兼容OpenAI API协议。这一设计决策背后有深刻的工程考量：业内绝大多数大模型项目最初都是基于OpenAI SDK起步的，代码结构、参数命名、消息格式已经与OpenAI的协议深度绑定。当团队想更换模型服务商时，最大的阻力往往不是模型本身的差异，而是代码改造成本。TokenHub通过协议兼容，让已使用OpenAI SDK的项目仅需修改base_url和API Key两个值即可完成接入，业务代码几乎无需改动。

TokenHub的协议兼容覆盖了全部18款语言模型和多模态接口。具体支持的协议包括：

• OpenAI Chat Completions API：平台主用的在线推理协议，所有语言模型均支持
• OpenAI Responses API：部分模型支持，对于原生仅支持Chat Completions的模型，TokenHub会在服务端自动完成协议转换
• Anthropic Messages API：适用于Token Plan套餐场景，方便Claude Code等工具接入

3.2 调用入口：Base URL配置

TokenHub提供两种不同的调用入口，分别对应不同的计费模式和适用场景：

• 在线推理入口（按量计费）：base_url为 https://tokenhub.tencentmaas.com/v1，完整调用地址为 https://tokenhub.tencentmaas.com/v1/chat/completions。适用于使用按量计费、批量任务、企业生产环境的标准API调用。国际站用户使用 https://tokenhub-intl.tencentmaas.com/v1。
• Token Plan入口（订阅套餐）：base_url为 https://api.lkeap.cloud.tencent.com/plan/v3，完整调用地址为 https://api.lkeap.cloud.tencent.com/plan/v3/chat/completions。适用于已购买Token Plan个人版或企业版的开发者。

3.3 请求参数说明

TokenHub网关支持的请求参数与OpenAI官方规范保持一致。核心参数包括：

• model：必填，字符串类型，指定调用的模型服务ID。对于平台默认创建的推理服务，服务ID与模型名称相同，完整列表见下文模型选型章节。对于用户创建的自定义推理服务，服务ID格式为 ep-xxxxxxxx。
• messages：必填，消息数组，包含对话历史。每条消息包含role（system/user/assistant）和content字段。
• stream：可选，布尔值，是否启用流式输出。
• temperature：可选，浮点数，控制输出随机性。
• max_tokens：可选，整数，限制最大输出Token数。

3.4 多语言代码调用示例

以下提供主流编程语言的完整调用示例，所有示例均使用在线推理入口。

cURL调用

curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek-v3",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "stream": true
  }'

Python（OpenAI SDK）

from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-v3",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Node.js（OpenAI SDK）

import OpenAI from "openai";

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

async function main() {
    const stream = await client.chat.completions.create({
        model: "deepseek-v3",
        messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: "你好，请介绍一下你自己" }
        ],
        stream: true
    });

    for await (const chunk of stream) {
        process.stdout.write(chunk.choices[0]?.delta?.content || "");
    }
}

main();

Java（OkHttp）

import okhttp3.*;
import org.json.JSONObject;

public class TokenHubExample {
    public static void main(String[] args) throws Exception {
        OkHttpClient client = new OkHttpClient();
        
        JSONObject json = new JSONObject();
        json.put("model", "deepseek-v3");
        json.put("stream", true);
        
        JSONArray messages = new JSONArray();
        JSONObject systemMsg = new JSONObject();
        systemMsg.put("role", "system");
        systemMsg.put("content", "You are a helpful assistant.");
        messages.put(systemMsg);
        
        JSONObject userMsg = new JSONObject();
        userMsg.put("role", "user");
        userMsg.put("content", "你好，请介绍一下你自己");
        messages.put(userMsg);
        
        json.put("messages", messages);
        
        Request request = new Request.Builder()
            .url("https://tokenhub.tencentmaas.com/v1/chat/completions")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .post(RequestBody.create(json.toString(), MediaType.parse("application/json")))
            .build();
        
        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "model": "deepseek-v3",
        "messages": []map[string]string{
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "你好，请介绍一下你自己"},
        },
        "stream": true,
    }
    
    jsonData, _ := json.Marshal(payload)
    
    req, _ := http.NewRequest("POST", 
        "https://tokenhub.tencentmaas.com/v1/chat/completions",
        bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

四、模型选型：18款语言模型全景解析

TokenHub当前提供18款语言模型，覆盖腾讯自研与多家第三方厂商。以下按厂商分类梳理各模型的调用参数与核心能力。

4.1 腾讯混元系列

4.2 DeepSeek系列

4.3 智谱GLM系列

4.4 Kimi系列

4.5 MiniMax系列

4.6 模型选型建议

根据不同场景需求，可参考以下选型方向：

• 代码生成与编程辅助：优先考虑Kimi-K2.6、Kimi-K2.7 Code系列或DeepSeek-V4-Pro
• 深度推理与复杂Agent：Hy3 preview或DeepSeek-V4-Pro
• 超长上下文处理：GLM-5.2（1M上下文）或MiniMax-M3（1M上下文）
• 高性价比通用对话：DeepSeek-V4-Flash或GLM-5-Turbo
• 多模态理解：GLM-5V-Turbo或MiniMax-M3

五、计费模式与成本优化

5.1 按量后付费（在线推理）

TokenHub的语言模型采用按Token计费的后付费模式。计费项分为三类：

• 推理输入：用户输入文本（含system prompt）的Token消耗，按元/百万tokens计价
• 推理输出：模型生成文本的Token消耗，按元/百万tokens计价
• 缓存输入：命中缓存的输入Token消耗，按元/百万tokens计价，价格远低于常规输入

输入Token和输出Token分别计价，不同模型的单价不同。部分模型支持分段定价，不同输入长度段对应不同单价。Token估算参考：中文约1.8字符≈1 Token，英文约0.75单词≈1 Token。

以下为广州地域部分模型的定价参考：

视觉模型采用不同的计费方式：图像生成按元/张计费，视频生成按元/秒或积分/秒计费，3D生成按积分/次计费。

5.2 预付费订阅套餐（Token Plan）

TokenHub提供多种预付费订阅套餐，适合高频调用场景：

• Coding Plan：面向AI编程场景的包月订阅套餐
• 通用Token Plan：面向龙虾和AI编程场景的包月订阅套餐，覆盖GLM、Kimi、MiniMax、DeepSeek等主流模型
• Hy Token Plan：面向Agent工作负载的专属订阅方案，集成Hy3 preview

订阅套餐采用积分池模式，月预算可自由设定，支持多套餐并行与多Key精细化分发。调用同样的模型，套餐价格比API按量计费便宜50%-80%，用量越大节省越多。

5.3 批量任务计费

TokenHub针对不同业务场景提供"在线推理"与"批量任务"两套独立的计费规则。在线推理用于实时交互场景，批量任务用于离线大批量处理，两者的计费方式、价格、缓存与限流规则有所不同，开发者可根据业务节奏选用最合适的计费组合以降低单位调用成本。

5.4 成本优化建议

• 善用免费额度：新用户务必领取免费体验包，在90天有效期内完成接口调试和功能验证
• 高频场景选用订阅套餐：对于日均调用量稳定的场景，Token Plan的预付费模式可大幅降低成本
• 利用缓存机制：缓存命中的输入Token价格远低于常规输入，对于重复性高的请求可显著降本
• 合理选择模型：根据场景复杂度选择合适模型，简单对话任务无需调用旗舰模型
• 批量任务走批量通道：离线大批量处理场景使用批量任务计费模式，避免按在线推理计费

六、企业级治理与高级功能

6.1 API Key精细化权限管理

TokenHub的API Key管理支持细粒度的权限控制。创建API Key时可以选择"全选"——一个Key调用平台已上架的全部模型；也可以选择"限定范围"——指定该Key仅可访问特定的模型或推理服务。这种设计让企业可以为不同团队、不同项目分配不同权限的API Key，实现最小权限原则，降低密钥泄露的风险。

API Key管理页面还支持启停切换和调用统计，方便运维人员对异常Key进行及时处置。

6.2 模型监控与可观测性

TokenHub提供模型监控功能，展示模型与服务性能相关指标，包括TTFT（首Token生成时间）、TPOT（每Token输出时间）、RPM（每分钟请求数）等。用量统计页面展示计费用量指标，包括输入Token、输出Token、TPM（每分钟Token数）、插件调用次数等。这些可观测性数据帮助开发团队及时发现性能瓶颈和异常调用。

6.3 自定义推理服务

除了调用平台默认的模型服务，TokenHub还支持用户在在线推理页面创建并管理自定义的推理服务实例，获取专属API Endpoint。自定义服务的服务ID格式为 ep-xxxxxxxx。这一能力让企业可以根据自身业务需求配置专属的推理环境。

6.4 智能创作Agent

TokenHub还提供智能创作Agent产品线，面向内容创作者和企业，提供视频特效与真人剧两大智能体。视频特效智能体已上线，真人剧智能体即将上线，两者均基于腾讯混元大模型实现"描述即生成"，适用于短视频、微短剧、品牌营销等场景。

七、常见问题解答

问1：TokenHub的API与OpenAI API完全兼容吗？

TokenHub完全兼容OpenAI Chat Completions API协议。使用OpenAI SDK的项目仅需将base_url替换为 https://tokenhub.tencentmaas.com/v1，并将api_key替换为在TokenHub控制台创建的API Key即可。业务代码中的消息格式、参数命名与OpenAI官方保持一致，几乎无需额外改动。

问2：一个API Key可以调用多少个模型？

一个API Key可以调用TokenHub平台已上架的全部18款语言模型及多模态模型。创建API Key时如果选择"全选"，则该Key可访问当前账号下所有模型和推理服务。如果选择"限定范围"，则只能访问指定的模型或服务。

问3：TokenHub支持哪些编程语言的SDK？

由于TokenHub兼容OpenAI API协议，所有支持OpenAI SDK的编程语言都可以直接使用。官方示例已覆盖Python、Node.js、cURL、Java、Go等主流语言生态。此外，任何支持HTTP请求的客户端都可以通过RESTful API方式调用。

问4：免费体验额度用完后如何继续使用？

免费体验额度用完后，需要开启指定模型的后付费功能才能继续调用。在模型广场选择需要使用的模型，开启"启用后付费"即可。TokenHub按实际用量从腾讯云账户扣费，也可以提前购买Token Plan订阅套餐享受更优惠的价格。

问5：TokenHub如何保障企业数据安全？

TokenHub提供多层安全保障机制。在权限层面，API Key支持精细化权限管控，可限定访问范围。在资源层面，提供从独立资源到共享池的多级保障能力。在治理层面，提供包含预算、权限、审计的可视化看板。企业还可以通过自定义推理服务实现专属的推理环境隔离。

问6：TokenHub与直接调用各家模型API有什么区别？

直接调用各家模型API需要在不同平台分别注册账号、分别管理API密钥、分别适配不同的调用协议。TokenHub提供统一入口，一个API Key、一套OpenAI兼容协议即可调用多家主流模型。此外，TokenHub还提供统一的用量统计、模型监控、预算管理和权限管控，大幅降低了多模型接入的运维复杂度。