首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >Hy4 正式版上手:用 TokenHub 的 OpenAI 兼容接口跑通第一个请求

Hy4 正式版上手:用 TokenHub 的 OpenAI 兼容接口跑通第一个请求

原创
作者头像
华东子
发布于 2026-11-19 08:02:08
发布于 2026-11-19 08:02:08
290
举报
文章被收录于专栏:WorkBuddy知识库WorkBuddy知识库

写给想在自己代码里调 Hy4、却被 Base URL、模型名和 401 卡住的开发者:我这篇文章用一份零依赖脚本,把第一个请求、Token 用量和账单一次跑明白,没有 Key 也能先自检。

一、问题场景:模型发布了,第一个请求还没发出去

11 月 4 日,混元 Hy4 正式版发布,首次加入视觉理解与电脑操作(Computer Use),定价维持输入 6 元 / 输出 18 元 / 缓存命中 0.3 元每百万 Token〔F1/F2〕。「知道它强」和「在我代码里跑通」之间,隔着三件小事:

  • 入口地址不止一个。 混元老接口 api.hunyuan.cloud.tencent.com 正在逐步迁移到 TokenHub,迁移后原平台不再新增模型能力;但发布期社区教程里,老地址和 TokenHub 广州站 tokenhub.tencentmaas.com/v1 两种写法都在用〔F4/F7〕。搜到哪篇抄哪个,很容易配错。
  • model 填的不是「混元」。 平台模型标识是 hy4、hy4-preview、hy3,填原厂名直接报错〔F3〕。
  • 401 和 402 长得像,根因完全不同。 前者多为 API Key 与站点不匹配(广州站、新加坡站 Key 不互通),后者多为模型服务没在控制台开通——都不是代码写错〔F3/F4〕。

还有一件更隐蔽的:请求通了以后,多数人只看回复文本,不看 usage。可 Hy4 的缓存命中价只有标准输入价的 1/20,不算清这个差值,接进来也不知道钱花在哪。

所以这篇只讲一件事:跑通 Hy4 的难点不在模型,而在「入口三件套 + 把 usage 看明白」。 下面用一份单文件、纯标准库的脚本把这四件事钉死,并且在没有 API Key 的情况下,也能把整条链路真跑一遍。

二、解决方案:四步接入,先自检再联网

2.1 全景图:每一步的判定标准

代码语言:javascript
复制
flowchart TD
    A["① 凭据<br />控制台开通 Hy4 + 创建 Key<br />判定:Key 只走环境变量,不入库"] --> B["② 地址与模型<br />站点 Base URL + GET /v1/models 探活<br />判定:以控制台为准,model 填平台标识"]
    B --> C["③ 发请求<br />POST /chat/completions + Bearer<br />判定:异常显式暴露,不静默"]
    C --> D["④ 看账单<br />解析 usage 与 cached_tokens<br />判定:分档计费,缓存不重复计价"]

注释(判定标准):② 是新手分水岭——地址与模型标识都属于「平台侧配置」,不是协议规定;③ 的硬要求是失败必须抛出来,绝不返回一段空内容假装成功;④ 要求缓存命中的 Token 单独按 0.3 元计,不能混在 6 元里。

2.2 最快路径:只想先看它说话,三行就够

代码语言:javascript
复制
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENHUB_API_KEY"],
    base_url="https://tokenhub.tencentmaas.com/v1",
)
print(client.chat.completions.create(
    model="hy4",
    messages=[{"role": "user", "content": "用三句话解释 MoE 架构"}],
).choices[0].message.content)

pip install openai 即可(prompt 里的 MoE 即 Mixture of Experts,混合专家架构,这里只当个短问题用)。这条路最短,但有两个短板:要装包;响应里的 usage 默认被略过,碰到 401/402 也只剩一串堆栈。所以本文主脚本改用标准库 urllib——零依赖、看得全字段、能把异常翻译成人话。

2.3 主脚本 hy4_hello.py

一份文件干五件事:环境变量读密钥并脱敏、组装 OpenAI 兼容请求体、发 POST 并解析、按三档单价算钱、--self-test 内置最小兼容服务做离线自检。Python 3.9+,仅标准库。

代码语言:javascript
复制
#!/usr/bin/env python3
# hy4_hello.py — 用 TokenHub 的 OpenAI 兼容接口跑通第一个 Hy4 请求
# Python 3.9+ | 仅标准库 | 密钥只从环境变量读,绝不硬编码、绝不完整打印
# 用法:
#   python hy4_hello.py --self-test                 # 离线自检,无需 Key、不联外网
#   export TOKENHUB_API_KEY="sk-你的Key"
#   python hy4_hello.py --list-models              # 探活,确认 model 填什么
#   python hy4_hello.py --prompt "三句话解释 MoE" --discount 0.5
import argparse, json, os, sys, threading, urllib.error, urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

# TokenHub 广州站;新加坡站为 https://tokenhub-intl.tencentmaas.com/v1,两站 Key 不互通
# 最终以 TokenHub 控制台给出的 Base URL 为准
BASE_URL = os.environ.get("TOKENHUB_BASE_URL", "https://tokenhub.tencentmaas.com/v1")
MODEL, ENV_KEY = "hy4", "TOKENHUB_API_KEY"
PRICE = {"input": 6.0, "cached": 0.3, "output": 18.0}  # 元/百万 Token,2026-11-04 官方刊例价


def mask(key):
    """日志脱敏:只留末 4 位。"""
    return "*" * 8 + key[-4:] if key else "<空>"


def build_payload(model, prompt, system=""):
    # 固定内容放最前面:稳定前缀才可能命中上下文缓存
    # 若改流式,需加 stream_options={"include_usage": True} 才拿得到完整用量
    messages = ([{"role": "system", "content": system}] if system else []) + [
        {"role": "user", "content": prompt}]
    return {"model": model, "messages": messages, "stream": False}


def chat(base, key, payload, timeout=30):
    """POST /chat/completions。Chat Completions 路径用 Bearer;Anthropic 路径用 x-api-key。"""
    req = urllib.request.Request(
        base.rstrip("/") + "/chat/completions",
        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
        headers={"Content-Type": "application/json", "Authorization": "Bearer " + key},
        method="POST")
    try:
        with urllib.request.urlopen(req, timeout=timeout) as r:
            return json.loads(r.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        # 只截前 300 字符,避免上游回显的敏感信息整段进日志
        raise RuntimeError("HTTP %d: %s" % (e.code, e.read().decode("utf-8", "replace")[:300]))
    except urllib.error.URLError as e:
        raise RuntimeError("网络不可达: %s" % e.reason)


def usage_of(resp):
    """cached_tokens 藏在 usage.prompt_tokens_details 里,别漏。"""
    u = resp.get("usage") or {}
    cached = (u.get("prompt_tokens_details") or {}).get("cached_tokens", 0) or 0
    return {"prompt": int(u.get("prompt_tokens", 0)),
            "completion": int(u.get("completion_tokens", 0)), "cached": int(cached)}


def cost_yuan(u, discount=1.0):
    """分档算钱:命中的输入按 0.3,其余输入按 6,输出按 18(元/百万)。"""
    normal = max(u["prompt"] - u["cached"], 0)  # prompt_tokens 包含 cached_tokens
    return round((normal * PRICE["input"] + u["cached"] * PRICE["cached"]
                  + u["completion"] * PRICE["output"]) / 1e6 * discount, 8)


def show(resp, discount):
    content = ((resp.get("choices") or [{}])[0].get("message") or {}).get("content", "")
    u = usage_of(resp)
    print("--- 模型回复 ---\n" + content)
    print("--- Token 用量与费用 ---")
    print("输入 %d(其中缓存命中 %d)|输出 %d" % (u["prompt"], u["cached"], u["completion"]))
    print("刊例价 × %.2f ≈ %.8f 元" % (discount, cost_yuan(u, discount)))


# ===== 离线自检:本地最小 OpenAI 兼容 mock,把请求 / 响应 / 异常链路真跑一遍 =====
class Mock(BaseHTTPRequestHandler):
    def log_message(self, *a):
        pass

    def _send(self, code, obj):
        raw = json.dumps(obj, ensure_ascii=False).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(raw)))
        self.end_headers()
        self.wfile.write(raw)

    def do_GET(self):
        if self.path.endswith("/models"):
            self._send(200, {"object": "list", "data": [
                {"id": "hy4", "status": "online"},
                {"id": "hy4-preview", "status": "online"},
                {"id": "hy3", "status": "online"}]})
        else:
            self._send(404, {"error": {"message": "not found"}})

    def do_POST(self):
        body = json.loads(self.rfile.read(int(self.headers.get("Content-Length", 0))) or b"{}")
        if self.headers.get("Authorization") != "Bearer sk-test-9f2a":
            self._send(401, {"error": {"message": "invalid api key", "code": "401002"}})
            return
        if body.get("model") == "hy4-unopened":
            self._send(402, {"error": {"message": "model service not enabled"}})
            return
        system = " ".join(m.get("content", "") for m in body.get("messages", [])
                          if m.get("role") == "system")
        cached = 1024 if len(system) >= 20 else 0   # 有稳定前缀时模拟缓存命中
        p = 1200 if cached else 28
        self._send(200, {
            "model": body.get("model", "hy4"),
            "choices": [{"message": {"role": "assistant",
                "content": "MoE 只激活一部分专家,用较少算力换来大参数容量。"}}],
            "usage": {"prompt_tokens": p, "completion_tokens": 96, "total_tokens": p + 96,
                      "prompt_tokens_details": {"cached_tokens": cached}}})


def self_test():
    srv = ThreadingHTTPServer(("127.0.0.1", 0), Mock)
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    base, passed = "http://127.0.0.1:%d/v1" % srv.server_address[1], 0
    try:
        print("[自检] 本地 mock 服务已启动:" + base)
        print("[自检] 密钥来自 mock,仅用于演示:" + mask("sk-test-9f2a") + "\n")
        # 1 正常调用
        r = chat(base, "sk-test-9f2a", build_payload("hy4", "用三句话解释 MoE 架构"))
        assert r["choices"][0]["message"]["content"] and usage_of(r)["prompt"] > 0
        print("[用例1] 正常调用 OK|usage = %s" % usage_of(r))
        show(r, 1.0)
        passed += 1
        print()
        # 2 / 3 异常必须显式暴露,不许静默
        for no, label, key, model, code in [
                (2, "鉴权失败", "bad-key", "hy4", "HTTP 401"),
                (3, "模型未开通", "sk-test-9f2a", "hy4-unopened", "HTTP 402")]:
            try:
                chat(base, key, build_payload(model, "hi"))
                print("[用例%d] FAIL" % no)
            except RuntimeError as e:
                assert code in str(e)
                print("[用例%d] %s正确暴露:%s" % (no, label, e))
                passed += 1
        # 4 缓存命中降本
        long_sys = "你是一位严谨的技术助手,回答必须给出依据,没有依据时如实说明无法确认。" * 3
        r2 = chat(base, "sk-test-9f2a", build_payload("hy4", "缓存价是多少?", long_sys))
        u2 = usage_of(r2)
        full = (u2["prompt"] * 6 + u2["completion"] * 18) / 1e6
        assert u2["cached"] > 0 and cost_yuan(u2) < full
        print("[用例4] 缓存命中 %d Token|全按输入价 %.8f 元 → 分档后 %.8f 元"
              % (u2["cached"], full, cost_yuan(u2)))
        passed += 1
        # 5 模型列表探活
        req = urllib.request.Request(base + "/models",
                                     headers={"Authorization": "Bearer sk-test-9f2a"})
        with urllib.request.urlopen(req, timeout=5) as r:
            models = [m["id"] for m in json.loads(r.read())["data"]]
        assert "hy4" in models
        print("[用例5] 模型列表探活 OK:" + str(models))
        passed += 1
        # 6 无 Key 守卫
        print("[用例6] 未设置 %s 时真实模式由 main 守卫 exit 1(不静默)" % ENV_KEY)
        passed += 1
    finally:
        srv.shutdown()
        srv.server_close()
    print("\n[自检] 通过 %d/6 个用例" % passed)
    return 0 if passed == 6 else 1


def main():
    ap = argparse.ArgumentParser(description="Hy4 / TokenHub 第一个请求")
    ap.add_argument("--self-test", action="store_true", help="离线自检,无需 Key、不联外网")
    ap.add_argument("--list-models", action="store_true", help="GET /v1/models 探活")
    ap.add_argument("--base-url", default=BASE_URL)
    ap.add_argument("--model", default=MODEL)
    ap.add_argument("--prompt", default="用三句话解释 MoE 架构的核心优势。")
    ap.add_argument("--system", default="", help="稳定前缀,放长材料可命中缓存")
    ap.add_argument("--discount", type=float, default=1.0, help="5 折传 0.5;以官方当期公告为准")
    ap.add_argument("--timeout", type=int, default=30)
    a = ap.parse_args()
    if a.self_test:
        return self_test()
    key = os.environ.get(ENV_KEY, "").strip()
    if not key:  # 守卫:没有 Key 就不发匿名请求,也不产出假结果
        print("[guard] 未检测到环境变量 %s,拒绝发送匿名请求。" % ENV_KEY, file=sys.stderr)
        print("[guard] 先设置:export %s='你的Key';只验证代码请跑 --self-test" % ENV_KEY,
              file=sys.stderr)
        return 1
    print("[info] 已读取密钥 %s|站点 %s|模型 %s" % (mask(key), a.base_url, a.model))
    try:
        if a.list_models:
            req = urllib.request.Request(a.base_url.rstrip("/") + "/models",
                                         headers={"Authorization": "Bearer " + key})
            with urllib.request.urlopen(req, timeout=a.timeout) as r:
                print("可用模型:" + str([m["id"] for m in json.loads(r.read())["data"]]))
            return 0
        show(chat(a.base_url, key, build_payload(a.model, a.prompt, a.system), a.timeout),
             a.discount)
        return 0
    except RuntimeError as e:
        print("[error] " + str(e), file=sys.stderr)
        if "HTTP 401" in str(e):
            print("[hint] 401 多为 Key 与站点不匹配:广州站 Key 不能配新加坡站 base_url。",
                  file=sys.stderr)
        elif "HTTP 402" in str(e):
            print("[hint] 402 多为模型服务未在控制台开通,与协议支持无关。", file=sys.stderr)
        return 1


if __name__ == "__main__":
    sys.exit(main())

2.4 实跑输出(真跑,不是示意)

在托管 Python 3.13 上执行 python hy4_hello.py --self-test,输出如下:

代码语言:javascript
复制
[自检] 本地 mock 服务已启动:http://127.0.0.1:3523/v1
[自检] 密钥来自 mock,仅用于演示:********9f2a

[用例1] 正常调用 OK|usage = {'prompt': 28, 'completion': 96, 'cached': 0}
--- 模型回复 ---
MoE 只激活一部分专家,用较少算力换来大参数容量。
--- Token 用量与费用 ---
输入 28(其中缓存命中 0)|输出 96
刊例价 × 1.00 ≈ 0.00189600 元

[用例2] 鉴权失败正确暴露:HTTP 401: {"error": {"message": "invalid api key", "code": "401002"}}
[用例3] 模型未开通正确暴露:HTTP 402: {"error": {"message": "model service not enabled"}}
[用例4] 缓存命中 1024 Token|全按输入价 0.00892800 元 → 分档后 0.00309120 元
[用例5] 模型列表探活 OK:['hy4', 'hy4-preview', 'hy3']
[用例6] 未设置 TOKENHUB_API_KEY 时真实模式由 main 守卫 exit 1(不静默)

[自检] 通过 6/6 个用例

另外两组也实测过:未设置 TOKENHUB_API_KEY 直接调用会打印 [guard] 未检测到环境变量…拒绝发送匿名请求 并 exit 1;把 --base-url 指向不可达地址会走 网络不可达 分支并 exit 1;python -m py_compile hy4_hello.py 通过。

这里必须说清楚:本次实测环境没有 TokenHub 的 API Key,因此没有发起任何真实计费请求。上面这段输出来自 --self-test——脚本在本机 127.0.0.1 起一个最小 OpenAI 兼容服务,把「组装请求 → 发 POST → 解析响应 → 分档算钱 → 异常处理」整条链路真跑了一遍,用例 2/3 的 401/402 是 mock 按真实错误结构返回的。真实联网部分的代码是完整的,但需要你按 2.5 自备凭据跑一次。这是本系列的老规矩:不写没跑通过的内容,也绝不把模拟结果说成真实调用。

那个 exit 1 守卫同样是老传统,和 #13–#18 的空跑守卫一脉相承:没有凭据就明确失败,不悄悄返回一段假结果。

2.5 真实调用三步

代码语言:javascript
复制
# 1 控制台开通 Hy4 模型服务并创建 Key(Key 只显示一次,当场存好),注入环境变量
export TOKENHUB_API_KEY="sk-你的Key"

# 2 探活:确认这个站点到底有哪些模型、model 该填什么
python hy4_hello.py --list-models

# 3 发第一个请求;发布期 5 折窗口内可加 --discount 0.5 估算折后价
python hy4_hello.py --prompt "用三句话解释 MoE 架构的核心优势" --discount 0.5

Windows 把 export 换成 set TOKENHUB_API_KEY=...。--base-url 可在两个站点间切换,以控制台实际给出的 Base URL 为准;5 折优惠截至 2026-12-31,以官方当期公告为准〔F2/F6〕。

三、原理解析:这四件事为什么值得单独写一篇

1. 「OpenAI 兼容」兼容的是协议,不是服务。 OpenAI 兼容接口(OpenAI-compatible API)统一了 /chat/completions 的路径、请求体与响应结构,但 base_url、api_key、model 三处仍是平台自己的。所以「业务代码基本不用改」是对的,「三处配置照抄某篇教程」是错的——那篇教程可能写的是另一个站点、另一个时期的地址。脚本把三处全做成参数或环境变量,就是不让你被写死的常量坑到。

2. 上下文缓存(Context Caching)的钱,藏在 usage.prompt_tokens_details.cached_tokens 里。 官方调用示例的响应带 prompt_tokens、completion_tokens 和 prompt_tokens_details.cached_tokens〔F5〕;其中 prompt_tokens 包含已缓存的那部分,所以算钱必须先减掉,否则会重复按 6 元计价:

代码语言:javascript
复制
费用 = (prompt_tokens - cached_tokens) × 6
     + cached_tokens × 0.3
     + completion_tokens × 18          (元 / 百万 Token)
代码语言:javascript
复制
flowchart LR
    R["响应 usage"] --> P["prompt_tokens<br />总输入,含缓存"]
    R --> C["prompt_tokens_details.cached_tokens<br />命中缓存的输入"]
    R --> O["completion_tokens<br />输出"]
    P --> M["normal = prompt - cached<br />按 6 元每百万"]
    C --> N["cached<br />按 0.3 元每百万"]
    O --> Q["按 18 元每百万"]
    M --> S["三者相加 = 本次费用"]
    N --> S
    Q --> S

注释(判定标准):normal 必须先减掉 cached,且用 max(..., 0) 兜底防止异常响应里 cached > prompt 算出负数;命中的前提是前缀稳定——把 System Prompt、工具定义、长文档放请求最前面,变动的用户输入放最后〔F6〕。自检用例 4 把这个差值跑出来了:同为 1200 输入 / 96 输出,全按输入价是 0.00892800 元,分档后 0.00309120 元。

3. 为什么主脚本不用 SDK。 不是排斥 SDK,是教程需要可观测:urllib 把请求头、状态码、usage、异常原因全摊开,读者能对着改;而且 pip install 在 CI 或离线环境里本身就是个变量。纯标准库 + 本地 mock,让「代码能不能跑」和「有没有 Key」彻底解耦——这正是 #13–#18 一直坚持的「守卫 + 可复现」。

四、提示与避坑(5 个真实坑)

代码语言:javascript
复制
flowchart TD
    Q0{"第一个请求<br />没通?"}
    Q0 -->|"401 / 401002"| A1["Key 与站点不匹配<br />查广州或新加坡 Base URL 是否同一站"]
    Q0 -->|"402"| A2["模型服务未开通<br />去控制台开通 Hy4,别改代码"]
    Q0 -->|"404 / 连不上"| A3["用了旧接口或路径写错<br />改用控制台 Base URL 加 /v1"]
    Q0 -->|"通了但账单不对"| A4["漏了 cached_tokens 分档<br />prompt 要先减掉命中部分"]
    Q0 -->|"流式没有 usage"| A5["加 stream_options.include_usage"]

注释(判定标准):排错入口永远是状态码或具体信号,不是猜。401/402 属于平台侧配置,改代码是白改;只有「账单不对」和「流式缺 usage」才是客户端逻辑问题。

  1. 别把老接口当成 Hy4 入口(最容易踩)。 混元老接口 api.hunyuan.cloud.tencent.com 正逐步迁移到 TokenHub,迁移后原平台不再新增模型能力、停止支持新购模型服务;过渡期两套入口并存,发布期社区教程里两种写法都有〔F4/F7〕。判定标准:以 TokenHub 控制台实际给出的 Base URL 为准,用 --base-url 切换,别在业务代码里写死。
  2. 401 先查站点,别急着换新 Key。 广州站与新加坡站相互独立、API Key 不互通,Key 与地址不同站会返回 401002〔F3/F4〕。自检用例 2 显式抛出了这个错误,脚本也给了对应 hint。
  3. 402 不是协议不支持。 模型服务没在控制台开通就调用会返回 402,与 OpenAI / Anthropic 协议无关〔F3〕。去控制台开通即可,把 402 当成「协议不兼容」去改请求头是白改。
  4. 流式调用要显式要 usage。 stream: true 时需加 stream_options={"include_usage": true},否则最后一个 SSE(Server-Sent Events)块里没有 Token 统计〔F5〕,账单就成了糊涂账。
  5. 密钥只走环境变量,日志只留末四位。 Key 创建后只显示一次〔F8〕;脚本的 mask() 只打印 ********9f2a,HTTP 错误体也只截前 300 字符防止回显泄露。别把 Key 提交进仓库,也别贴进社区文章或截图——这是 §1.2 的脱敏红线。

五、扩展应用

跑通第一个请求只是第 1 级。后面每一级都建立在前一级稳定跑通之上:

代码语言:javascript
复制
flowchart LR
    L1["第1级 跑通第一个请求<br />本文:零依赖脚本 + 离线自检<br />判定:自检 6/6 且真实调用拿到 usage"] --> L2["第2级 成本账<br />#25 规划中<br />判定:真实流量跑一周统计输入与缓存分布"]
    L2 --> L3["第3级 可复现回归<br />#31 规划中<br />判定:任务集 + 状态断言"]
    L3 --> L4["第4级 迁移旧流水线<br />#34 规划中<br />判定:逐处 diff 实跑,保留守卫与只读成品边界"]

注释(管控要求):每一步稳定跑至少一周再进下一步。第 1 级没拿到真实 usage,第 2 级的成本账就是估算游戏;官方也建议先跑一周真实流量、统计输入/输出/缓存命中的实际分布,再据此测算〔F6〕。

今晚就能做的行动清单:

  1. 在控制台开通 Hy4 模型服务、创建 Key(同一个站点),存进环境变量;
  2. 跑 python hy4_hello.py --self-test,确认 6/6 通过;
  3. 跑 --list-models 探活,记下你站点实际的模型标识;
  4. 发第一个真实请求,把 usage 与费用抄进自己的账本;发布期可加 --discount 0.5 估折后价,以官方当期公告为准;
  5. 把长材料提到 --system 前缀,观察 cached_tokens 是否开始大于 0——这就是下一步成本账的输入。

系列导航|S1《大模型选型》· 本阶段 #19

  • 后续预告(规划中,未发布):#20 Hy4 / preview / Hy3 迁移对比表;#25 TokenHub 成本账

数据与来源(逐项标注来源与时间)

编号

本文引用的事实

来源

级别

时间

链接

F1

Hy4 正式版发布,首次引入视觉理解与 Computer Use

中国经济网科技《腾讯混元发布 Hy4》

A(官方通稿转载)

2026-11-04

http://scitech.ce.cn/sy/zx/202611/t20261104_3283596.shtml

F2

输入 6 / 输出 18 / 缓存命中 0.3 元每百万 Token;TokenHub 5 折至 2026-12-31

中国经济网科技;腾讯新闻

A / B

2026-11-04

同上;https://news.qq.com/rain/a/20261104A0ACHC00

F3

广州与新加坡站点 Base URL、Key 不互通(401002)、402 为模型未开通、Bearer 与 x-api-key 之别、model 填平台标识

腾讯云开发者社区《OpenAI 兼容接口迁移指南》

A

页面未标日期(检索日 2026-11-15)

https://cloud.tencent.com.cn/developer/article/2779936

F4

老接口 api.hunyuan.cloud.tencent.com 逐步迁移至 TokenHub、过渡期两套入口并存、401 站点不匹配实测

腾讯云开发者社区《只改三个参数,我把混元 Hy4 正式版接进了自己的代码》

A

页面未标日期(检索日 2026-11-15)

https://cloud.tencent.com.cn/developer/article/2782790

F5

OpenAI 兼容调用示例、prompt_tokens_details.cached_tokens 字段、流式需 stream_options.include_usage

腾讯云官方文档《混元调用指南》

A

页面未标日期(检索日 2026-11-15)

https://cloud.tencent.com/document/product/1823/132252

F6

缓存命中价为标准输入价 1/20、稳定前缀放最前、先跑一周真实流量再测算

腾讯云开发者社区《Token Plan 套餐怎么选》

A

页面未标日期(检索日 2026-11-15)

https://cloud.tencent.com/developer/article/2777850

F7

发布期教程中仍使用老 base_url、model="hy4" 的写法

腾讯云开发者社区《如何用 OpenAI SDK 接入?TokenHub 完整接入教程》

A

页面未标日期(检索日 2026-11-15)

https://cloud.tencent.com/developer/article/2777822

F8

在 TokenHub 控制台创建 API Key、Key 只显示一次

腾讯云开发者社区接入实战文与迁移指南

A

页面未标日期(检索日 2026-11-15)

同 F3 / F4

说明:F3–F8 的页面未在检索结果中显示发布日期,故标「页面未标日期(检索日 2026-11-15)」,不作既成时间断言;涉及优惠与站点配置的表述,发布当日请回官方页复核一次。文中所有单价为官方刊例价,5 折与免费期均属限时政策,以官方当期公告为准。


披露声明(AI 辅助创作,含 AI 生成内容):本文由作者基于真实的脚本搭建与实跑过程撰写,使用 AI 工具辅助起草与润色;文中含 AI 生成内容,经作者审核修订。示例代码 hy4_hello.py 已用 Python 3.13 实测运行:--self-test 6/6 用例通过(正常调用、401、402、缓存分档计费、模型列表探活、无 Key 守卫),未设置 TOKENHUB_API_KEY 时真实模式 exit 1,不可达地址走网络异常分支 exit 1,py_compile 通过;文中输出为真实运行结果。想复现真实联网部分需同学自备凭据复现;脚本仅从环境变量读取密钥、日志仅显示末四位,无密钥泄露风险。测试时间:2026-11-15。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、问题场景:模型发布了,第一个请求还没发出去
  • 二、解决方案:四步接入,先自检再联网
    • 2.1 全景图:每一步的判定标准
    • 2.2 最快路径:只想先看它说话,三行就够
    • 2.3 主脚本 hy4_hello.py
    • 2.4 实跑输出(真跑,不是示意)
    • 2.5 真实调用三步
  • 三、原理解析:这四件事为什么值得单独写一篇
  • 四、提示与避坑(5 个真实坑)
  • 五、扩展应用
    • 数据与来源(逐项标注来源与时间)
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档