腾讯 TokenHub API 接入指南

先确认站点、服务权限与模型

本指南使用腾讯TokenHub的OpenAI兼容Chat Completions接口。前提是已有获授权的账号、相应地域的TokenHub API Key，并已开通拟调用的模型服务。协议兼容说明请求格式，不说明平台销售全部OpenAI或Anthropic模型；不要因客户端名称推断GPT或Claude供应情况。

先记录站点、地域、计费账号、模型服务开通状态及网络访问方式。模型目录和账号开通是两项检查：列表中的online状态可帮助选型，但不能替代该账号的模型授权、余额与配额核对。Responses、工具、缓存、推理和多模态能力也要按具体模型分别确认。

选择当前地域端点

当前默认OpenAI兼容Base URL为新加坡 https://tokenhub-intl.tencentmaas.com/v1 或广州 https://tokenhub.tencentmaas.com/v1。以下以新加坡为例，Key与服务开通站点、地域必须一致，不能跨站点混用。不要照搬旧教程中的其他域名；若需备用接入，按官方当期表格核对后再实施。

新加坡的资源调度范围为全球，不能把新加坡接入当成推理只在新加坡进行的保证。广州的调度范围与国际站不同。涉及敏感资料时先确认实际处理、日志和合同条件，不通过切换域名绕过既定数据边界。

安装、查询真实模型ID

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

以下为占位配置；由授权服务端环境安全注入 TOKENHUB_API_KEY，不要把Key放入浏览器或仓库。先保留模型占位值，查询后再填写。

export TOKENHUB_BASE_URL='https://tokenhub-intl.tencentmaas.com/v1'
export TOKENHUB_MODEL='YOUR-ACTUAL-ONLINE-MODEL-ID'

保存以下初始化到 tokenhub_chat.py。client.models.list()对应带Bearer认证的 GET /v1/models，只输出模型ID与status，不输出密钥。选择当前列表中的online文本模型，另在控制台核对该账号服务已开通，再把ID填入 TOKENHUB_MODEL。不要从示例日期推断型号长期可用。

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["TOKENHUB_BASE_URL"],
    api_key=os.environ["TOKENHUB_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
for item in client.models.list().data:
    print(item.id, getattr(item, "status", "status unavailable"))

发出最小聊天请求

确认测试权限和费用后，把以下代码接在初始化后运行 python tokenhub_chat.py。先选支持普通文本与 max_tokens 的模型。128输出上限、30秒客户端超时和0次SDK自动重试都是示例控制值，不是平台配额或响应承诺。

request = {
    "model": os.environ["TOKENHUB_MODEL"],
    "messages": [{"role": "user", "content": "Reply with one short greeting."}],
    "max_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
    raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print("finish_reason:", answer.choices[0].finish_reason)
print(answer.usage.model_dump() if answer.usage else "usage unavailable")

检查finish reason，区分正常完成、长度截断、内容过滤与工具请求。HTTP200或收到一段文本，不足以证明业务问题已解决。首次测试保持单次短请求，确认计量和权限后再考虑并发。

流式输出与用量

用下面代码替换非流式调用。检查空choices，读取 delta.content 并单独保存usage；结束原因出现后继续读取至流结束，避免漏掉尾部用量块。不同模型的缓存明细可能不同，没有usage不能视作零收费。此例不解析推理内容或工具参数。

from openai import APIError

usage = None
finish_reason = None
try:
    with client.chat.completions.create(
        **request, stream=True, stream_options={"include_usage": True}
    ) as events:
        for part in events:
            if part.usage is not None:
                usage = part.usage
            if not part.choices:
                continue
            choice = part.choices[0]
            if choice.delta.content:
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason is not None:
                finish_reason = choice.finish_reason
except APIError:
    print("Stream failed; partial output is not a completed task.")
    raise
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")

SDK异常必须记录为失败。自写SSE解析器还要识别流中 error 帧；即使响应头已是200，也可能中途出错。不要把部分回答写成成功结果，或在重试时重复执行外部动作。

错误排查与验收

• 401/401002：检查Key与新加坡/广州站点是否匹配及是否有效。
• 402或402xxx：检查模型服务开通、额度与计费安排，不能误判为不支持该协议。
• 400/404：核对真实ID、API路径和模型可用参数，先移除可选功能。
• 429/429xxx：检查调用量、Token和并发；有Retry-After时遵循等待提示，并限制退避重试总量。
• 超时/5xx/流错误：保留脱敏请求编号和时间，核对任务状态后决定重试，不记录完整认证头。

按模型与调用路径保存用量，核对缓存、推理及附加功能费用；不要套用其他渠道价格或预先承诺节省。上线前测试截断、空用量块、中途失败、权限与额度不足，并设置并发、输出与总任务时限。日志最小化、密钥轮换和退出安排由实际账号负责人落实。

本例只作离线语法与合成流检查，未读取真实Key、查询你的模型列表或调用模型；账号可用性与费用须在获授权环境验证。

官方依据

核验日期：2026-10-17。

• TokenHub API、地域与模型列表
• 模型协议支持与错误分类
• Chat Completions字段与流错误