腾讯云人脸融合API必须用POST+JSON调用，image/template字段为纯base64（不含data:前缀），需V3签名且SecretKey要rtrim换行，响应Image需加data:image/png;base64,前缀才能显示。
腾讯云人脸融合 API 的 PHP 调用必须走 POST + JSON，不是 GET 或表单提交
腾讯云 AI 人脸融合（face-fusion）接口不支持直接传图片文件流或 base64 字符串到 URL 参数里，必须用 POST 请求体发送标准 JSON，且需带 Content-Type: application/json。很多人卡在 400 或 “invalid parameter” 就是因为拼了 URL 查询参数，或者用了 multipart/form-data。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data))发送请求体，别用http_build_query() -
$data中的image和template字段必须是合法 base64 字符串（不含data:image/png;base64,前缀） - base64 编码前先用
file_get_contents()读取本地图片，再base64_encode()，别直接对路径字符串编码 - 模板 ID（
template_id）要从腾讯云控制台「人脸融合模板管理」里复制真实 ID，不是模板名或 URL
PHP 签名生成容易错在 SecretKey 末尾换行、时间戳偏差和签名原文拼接顺序
腾讯云所有 API 都要签 V3 签名（TC3-HMAC-SHA256），PHP 实现时最常踩的坑是：SecretKey 从控制台复制下来带了不可见换行符；X-TC-Timestamp 超过 15 分钟导致签名失效；还有签名原文里把 HTTP 方法、路径、查询参数、头部、payload 的拼接顺序搞反。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 用
rtrim($secretKey, "\n\r")清掉SecretKey末尾空白 - 用
time()生成X-TC-Timestamp，别用date('U')或手动写时间戳 - 签名原文第 4 行是
payload的 SHA256 哈希值（空 payload 也要填e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855），不是原始 JSON 字符串 - 直接用腾讯云官方 SDK（
tencentcloud-sdk-php）比手写签名稳得多，尤其生产环境
返回结果里的 Image 是 base64，不是 URL，别直接丢进 <img src> 不处理
调用成功后响应 JSON 里 Image 字段是纯 base64 字符串（例如 /9j/4AAQSkZJR...），不是带 data: 前缀的完整 Data URL。有人直接塞进 HTML 的 src 属性，浏览器报错解析失败。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 输出前手动加前缀：
"data:image/png;base64," . $response['Image'] - 如果要存文件，先
base64_decode($response['Image'])，再file_put_contents("output.png", ...) - 注意响应里可能有
SessionId，腾讯云要求后续查询任务状态或下载结果时带上它（某些异步场景） - 失败时检查
Code和Message字段，常见错误如InvalidParameter.ImageFormatError（图片不是 PNG/JPG）、ResourceNotFound.TemplateIdNotFound（模板 ID 错或未发布）
免费额度用完后 403 错误没提示计费问题，得查控制台配额和账单
新账号默认有 1000 次/月人脸融合免费调用，用完后接口直接返回 403 Forbidden + UnauthorizedOperation，但错误信息里不会写“你欠费了”或“额度超限”，容易误判为权限或签名问题。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 登录腾讯云控制台 →「费用中心」→「用量查询」，筛选产品「人脸识别」，看
FaceFusion本月已用次数 - 确认是否开通了按量付费，没开的话即使充值了也无法继续调用
- 临时调试可用小图（
width < 300px）+ 低质量参数（quality=70）省额度，但注意影响融合效果 - 正式项目务必提前在控制台设置用量告警，阈值设 80% 免费额度
真正麻烦的是模板审核周期和 base64 大小限制——单张图 base64 超过 8MB 就会拒绝，而手机拍的原图很容易超。别等报错才压缩，上传前先用 imagejpeg($im, null, 85) 控制体积。
