腾讯混元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 换行符用 rn 还是 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 TencentCloudCommonCredential; use TencentCloudCommonProfileClientProfile; use TencentCloudCommonProfileHttpProfile; use TencentCloudHunyuanV20230901HunyuanClient; use TencentCloudHunyuanV20230901ModelsChatCompletionsRequest; $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。