腾讯混元API必须使用TC3-HMAC-SHA256签名机制，通过Authorization头传递，且需用官方SDK（tencentcloud-sdk-php）、region设为ap-guangzhou、绑定QcloudHunYuanFullAccess策略并开通服务。
混元 API 的鉴权方式不是 AccessKey + SecretKey 直接拼签名
腾讯混元（HunYuan）API 不接受传统 AWS 风格的 HMAC-SHA256 签名，也不允许把 SecretId 和 SecretKey 明文塞进请求头或参数。它强制使用腾讯云统一的 TC3-HMAC-SHA256 签名机制，且必须通过 Authorization 请求头传递完整签名串——这意味着你不能靠简单 curl_setopt($ch, CURLOPT_HTTPHEADER, [...]) 手动拼一个 header 就完事，必须严格按腾讯云规范生成时间戳、随机串、规范化请求、签名密钥派生等步骤。
常见错误现象：
• 返回 {"Error":{"Code":"AuthFailure.SignatureFailure","Message":"The provided signature does not match."}}
• 或直接 401，但没给出具体 Code
• 甚至返回 403 且提示 InvalidParameter（其实是签名层校验失败后，后续参数解析被跳过）
PHP 中必须用腾讯云官方 SDK（tencentcloud-sdk-php）对接混元
手动实现 TC3 签名逻辑在 PHP 中极易出错：时区不一致导致 X-TC-Timestamp 偏差、sha256 多层哈希顺序错一层、CanonicalRequest 换行符用 \r\n 还是 \n、signedHeaders 排序遗漏、credentialScope 里 service 字段写成 hunyuan 而非 hunyuan（实际是 hunyuan，但文档曾写错为 hunyuan，务必以控制台「API Explorer」生成的示例为准）。
实操建议：
• 用 Composer 安装最新版：
composer require tencentcloud-sdk-php
• 初始化客户端时，
region 必须设为 ap-guangzhou（混元目前仅此地域开放）•
Credential 对象中传入的 secretId 和 secretKey 必须来自「访问管理 > API 密钥管理」，不能是子用户未授权的密钥• 不要尝试复用其他腾讯云产品（如 COS、CVM）的 client 实例，混元有独立
HunyuanClient
立即学习“PHP免费学习笔记（深入）”；
调用 ChatCompletions 接口生成文案的最小可行代码
混元当前（2024 年中）主推接口是 ChatCompletions（路径 /v20230901/chat/completions），不是旧版 TextToText。它的 body 是标准 OpenAI 兼容格式，但鉴权仍走 TC3。
关键点：
• model 参数必须是字符串，如 "hunyuan-pro" 或 "hunyuan-standard"，不能省略或填空
• messages 至少含一个 {"role": "user", "content": "..."}
• temperature、top_p 等参数若不传，服务端会用默认值，但显式传 0.7 更可控
• 响应体结构和 OpenAI 类似，但字段名带 Response 后缀（如 Choices[0].Message.Content）
use TencentCloud\Common\Credential;
use TencentCloud\Common\Profile\ClientProfile;
use TencentCloud\Common\Profile\HttpProfile;
use TencentCloud\Hunyuan\V20230901\HunyuanClient;
use TencentCloud\Hunyuan\V20230901\Models\ChatCompletionsRequest;
$cred = new Credential("YOUR_SECRET_ID", "YOUR_SECRET_KEY");
$httpProfile = new HttpProfile();
$httpProfile->setEndpoint("https://hunyuan.tencentcloudapi.com");
$clientProfile = new ClientProfile();
$clientProfile->setHttpProfile($httpProfile);
$client = new HunyuanClient($cred, "ap-guangzhou", $clientProfile);
$req = new ChatCompletionsRequest();
$req->setModel("hunyuan-pro");
$req->setMessages([["Role" => "user", "Content" => "写一段 100 字以内关于春天的文案"]]);
$req->setTemperature(0.6);
try {
$resp = $client->ChatCompletions($req);
echo $resp->getChoices()[0]->getMessage()->getContent();
} catch (\Exception $e) {
echo $e->getMessage();
}
容易被忽略的权限与配额问题
即使签名完全正确，也会因以下原因失败：
• 主账号未在「腾讯云控制台 > 访问管理 > 授权策略」中给该密钥绑定 QcloudHunYuanFullAccess 策略（子用户需额外申请）
• 控制台「混元大模型」服务页未完成「开通服务」操作（免费额度需手动领取，否则调用直接报 ResourceUnavailable）
• 请求频率超限：新账号默认 QPS=1，突发请求会返回 LimitExceeded，需提工单调高
• 输入文本长度超限：当前 hunyuan-pro 最大 context 长度约 32768 token，但 PHP 中 mb_strlen($text) ≠ token 数，建议用官方提供的 tencentcloud-sdk-php 内置的 tokenizer 或先调用 CountTokens 接口预估
真正卡住人的，往往不是签名怎么算，而是控制台里那几个开关没打开、策略没绑、服务没开通——这些地方没有报错提示指向它们，只给你一个模糊的 UnauthorizedOperation。
