腾讯云 TokenHub 混元 Lite 长期免费，开通即赠百万 tokens 体验额度

混元提供兼容 OpenAI 协议的接口，用现成的 OpenAI SDK 就能接入，把 base_url 指向 https://api.hunyuan.cloud.tencent.com/v1 即可；接口域名与可用模型列表以控制台和官方文档为准。

用 curl 发一次对话补全请求

先把密钥写进环境变量，避免在代码里硬编码：

export HUNYUAN_API_KEY="sk-你的密钥"

再发送一次非流式的 /chat/completions 请求：

curl https://api.hunyuan.cloud.tencent.com/v1/chat/completions \
  -H "Authorization: Bearer $HUNYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hunyuan-lite",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手"},
      {"role": "user", "content": "用一句话说明什么是 API"}
    ],
    "temperature": 0.7,
    "top_p": 0.8,
    "max_tokens": 256,
    "stream": false
  }'

Python 侧可直接复用 OpenAI 官方 SDK，只需替换 base_url 与 api_key：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://api.hunyuan.cloud.tencent.com/v1",
)

resp = client.chat.completions.create(
    model="hunyuan-lite",
    messages=[{"role": "user", "content": "写一句产品文案"}],
    temperature=0.7,
    max_tokens=256,
)
print(resp.choices[0].message.content)

关键参数与模型选择

• model：免费额度对应 hunyuan-lite；hunyuan-turbo、hunyuan-pro 等属于按量计费模型，准确模型名以控制台模型列表为准。
• messages：消息数组，支持 system、user、assistant 三种角色，多轮对话需要把历史消息按顺序一并传入。
• temperature 与 top_p：控制输出随机性，取值 0 到 1；问答类场景 0.5 到 0.7 较稳定，创意类可适当调高。
• max_tokens：单次回复的最大 token 数，设得过小会导致内容被截断；免费额度的并发与速率上限以控制台限额说明为准。
• stream：设为 true 时按 SSE 逐块返回结果，适合做前端打字机效果。

额度耗尽或限流的排查顺序

1. 先看错误码：429 多为触发限流或并发超限；401、403 多为密钥错误、未实名或服务未开通；提示余额不足则说明账户欠费。
2. 核对模型名：确认 model 填的是免费模型 hunyuan-lite，误写成付费模型会直接产生计费并很快耗尽赠送额度。
3. 查额度：回到混元控制台查看赠送 tokens 的剩余量与有效期，确认是否已到期，或被同账号下其他应用消耗。
4. 降低请求频率：对 429 采用指数退避重试，减少并发请求数，避免短时间批量压测。
5. 检查网络与密钥：确认请求域名正确、环境变量已生效，密钥是否被删除、禁用或轮换。