必须先完成api密钥配置和基础参数设置，否则请求返回401错误；需在腾讯云控制台创建并安全保存sk-开头的api key，通过curl验证有效性；base_url设为https://tokenhub.tencentmaas.com/v1/，authorization头为bearer your_api_key，model指定hy3等合法id；python可选官方sdk（需secretid/key）或openai sdk（零改造，仅改api_key和base_url）。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在自己的程序里调用腾讯混元大模型的对话接口，必须先完成 API 密钥配置和基础请求参数设置，否则所有请求都会返回 401 错误或鉴权失败提示。
获取并验证混元 API 密钥
登录 腾讯云混元控制台 → 进入「API Key 管理」页面 → 点击「新建 API Key」→ 填写名称（如 dev-test）→ 点击确认。【SecretKey 仅在创建时显示一次，关闭页面即永久丢失】
复制生成的 API Key（格式为 sk-开头的字符串），立即保存到安全位置。不要截图、不要明文存本地文件，建议使用密码管理器。
打开终端执行以下命令验证密钥有效性：
curl -X POST "https://tokenhub.tencentmaas.com/v1/chat/completions" -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" -d '{"model":"hy3","messages":[{"role":"user","content":"测试"}]}'
若返回包含 "choices" 字段的 JSON，则密钥可用；若返回 "error": {"code": "Unauthorized", ...}，说明密钥错误或未激活。
配置 OpenAI 兼容接口参数
混元对话接口完全兼容 OpenAI Chat Completions 协议，只需替换 base_url 和 Authorization 头即可复用现有代码。
base_url 必须设为：https://tokenhub.tencentmaas.com/v1/（注意末尾斜杠不可省略）
Authorization 头格式为：Bearer YOUR_API_KEY，其中 YOUR_API_KEY 替换为你上一步复制的 sk-xxx 字符串。
model 参数必须指定合法模型 ID，例如：hy3、hy3-preview 或 hunyuan-standard。传入不存在的 model（如 hunyuan-v4）会导致 404 错误。
Python SDK 调用配置（推荐方式）
第一步：安装腾讯云官方 SDK
pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python
第二步：设置环境变量（Linux/macOS）
export TENCENTCLOUD_SECRET_ID="your-secret-id"export TENCENTCLOUD_SECRET_KEY="your-secret-key"
⚠️ 注意：SecretId 和 SecretKey 是腾讯云通用密钥对，不是 API Key；若你只申请了 API Key（sk-xxx），则不能用于此 SDK 方式，必须改用 HTTP 直连或 OpenAI SDK。
第三步：初始化客户端并指定地域
混元服务目前仅支持广州地域（ap-guangzhou），初始化 client 时 region 参数必须填 "ap-guangzhou"，填其他地域会报错 InvalidRegion。
OpenAI Python SDK 配置（零改造接入）
方法一：直接修改 openai 客户端初始化参数
将原代码中 openai.OpenAI() 初始化改为：
client = openai.OpenAI( api_key="sk-xxx", base_url="https://tokenhub.tencentmaas.com/v1/")
方法二：通过环境变量注入（适合部署环境）
export OPENAI_API_KEY="sk-xxx"export OPENAI_BASE_URL="https://tokenhub.tencentmaas.com/v1/"
之后所有 client.chat.completions.create(...) 调用自动走混元服务，无需修改业务逻辑。
