必须开通混元服务并获取SecretId/SecretKey；选对区域Endpoint（如广州或北京）；严格按TencentCloudSDK规范生成HMAC-SHA256签名，含X-TC-Action、X-TC-Timestamp等字段。
腾讯混元 API 调用前必须确认的三件事
PHP 不能直接“调用混元大模型”，它只能通过 HTTP 请求对接腾讯云提供的 hunyuan-api 接口。你得先有合法凭证、选对 endpoint、处理好鉴权，否则连 401 Unauthorized 都收不到——直接卡在 DNS 或连接超时。
- 必须开通腾讯云「混元」服务，并在控制台获取
SecretId和SecretKey（不是 AppID） - 接口地址不是固定域名，不同区域不同：
https://hunyuan.tencentcloudapi.com（广州）或https://hunyuan.ap-beijing.tencentcloudapi.com（北京），填错就404 - 签名必须用
TencentCloudSDK方式生成（HMAC-SHA256 + 拼接规范字符串），手写容易漏掉X-TC-Action或X-TC-Timestamp字段
用 curl 发起最简请求生成营销文案
别急着装 SDK，先用原生 curl 验证通路。混元的文案生成走的是 ChatCompletions 接口，但参数名和 OpenAI 不兼容——比如不能传 model，得传 Model（首字母大写），且值必须是 hunyuan-pro 或 hunyuan-standard。
- POST 到
https://hunyuan.tencentcloudapi.com，Header 必须带：Content-Type: application/json、Authorization: <your_sign_string></your_sign_string>、X-TC-Action: ChatCompletions、X-TC-Version: 2023-09-01 - Body 是 JSON，
Messages是数组，每项含Role（"user"或"assistant"）和Content（字符串），不能嵌套对象 - 示例 prompt 可以是：
"请为一款低糖燕麦奶写 3 条小红书风格的推广文案，每条不超过 30 字"；太模糊会返回空数组或"content filtering"
{"Model":"hunyuan-pro","Messages":[{"Role":"user","Content":"请为一款低糖燕麦奶写 3 条小红书风格的推广文案，每条不超过 30 字"}],"Stream":false}
常见报错和对应解法
混元返回的错误信息藏在响应体里，不是 HTTP 状态码。比如 400 响应体可能是 {"Error":{"Code":"InvalidParameterValue","Message":"Messages cannot be empty"}}，这时候光看状态码没用。
-
Code: AuthFailure.SignatureFailure→ 签名里漏了X-TC-Region，或时间戳偏差超过 300 秒（用time()就行，别用microtime()） -
Code: FailedOperation.NotEnoughBalance→ 账户余额不足 0.01 元，混元按 token 扣费，hunyuan-pro输入 1k token ≈ ¥0.008 -
Code: InvalidParameterValue且Message含"Content"→ 提示内容含敏感词（如“最”“第一”“ guaranteed”），换说法重试
PHP 处理响应和提取文案的坑
混元返回的 Choices 是数组，但 Message.Content 是纯文本，没有 markdown 或结构化字段。如果你要解析成多条文案，得靠自己切分——别信 str_split()，中文标点后换行不稳定，用正则更靠谱。
立即学习“PHP免费学习笔记（深入）”；
- 响应 body 要用
json_decode($res, true)，否则->Choices会报错 - 安全起见，先判断
isset($data['Choices'][0]['Message']['Content'])，再取值，混元可能返回空Content而不报错 - 切文案示例：
preg_split('/(?，适配「1、」「2.」或换行分隔
混元对长文本的截断逻辑不透明，如果输入含大量背景说明，输出可能被静默截断——把关键指令放在 Content 开头，别堆在后面。
