腾讯云人脸特效API不支持PHP SDK直接调用，需手动调用facefusion REST接口，严格签名、multipart上传、校验图片格式与参数，并复用官方签名逻辑。
腾讯云人脸特效 API 不支持 PHP SDK 直接调用
腾讯云目前没有为 人脸特效（如贴纸、美颜、AR 滤镜）提供官方 PHP SDK。你查到的 TencentCloud\Iai\V20200303\IaiClient 或其他 PHP SDK 仅覆盖基础人脸识别（检测、比对、搜索），不包含人脸特效能力。
这意味着：你不能像调用 detectFace 那样，用 PHP SDK 一行代码发起贴纸或美颜请求。
常见错误现象：Call to undefined method TencentCloud\Iai\V20200303\IaiClient::faceFusion() 或类似报错 —— 因为该方法根本不存在于当前 PHP SDK 中。
真实使用场景只有两种：要么走腾讯云官方 REST API（需手动签名 + HTTP 请求），要么改用他们明确支持的客户端语言（如 Python、Java、iOS/Android SDK）。
立即学习“PHP免费学习笔记（深入）”；
必须手写签名 + POST 调用 facefusion 接口
腾讯云人脸特效（如贴纸融合）实际走的是 facefusion 接口（属于「人脸融合」产品线），不是 IAI（图像分析）下的子服务。它要求严格按规范生成 Authorization 签名头，且 body 必须是 multipart/form-data 格式上传图片 + JSON 参数。
容易踩的坑：
- 直接用
file_get_contents读图后 JSON encode 发送 —— 错，接口不接受 base64 图片字段，只认image和mask这两个 form field - 忽略
X-TC-Action、X-TC-Version、X-TC-Region这三个必需 header - 签名时用了错误的
Service名 —— 正确值是facefusion，不是iai或cv - POST 的
Content-Type写成application/json—— 必须由 curl 自动设置 multipart boundary，不能手动指定
实操建议（以融合贴纸为例）：
腾讯云通用票据识别高级版(VatInvoiceOCR)接口调用技能。当用户需要识别发票图片中增值税专用发票、增值税普通发票、增值税电子专票、增值税电子普票、电子发票（普通/增值税专用）的全字段信息时,应使用此技能。支持识别发票图片中的发票代码、发票号码、开票日期、合计金额、校验码、税率、合计税额、价税合计、购买方...
- 用
cURL发起 POST，CURLOPT_POSTFIELDS传关联数组（含image、model、rfu等键），让 curl 自动处理 multipart - 签名算法必须用
HmacSHA256，密钥拼接顺序和字符串规范化（CanonicalRequest）要完全对标腾讯云文档 - 推荐先用腾讯云「API Explorer」调试通一个请求，再把生成的 Authorization 头和请求结构照搬到 PHP
facefusion 接口对输入图有硬性限制
不是所有 JPG/PNG 都能过审。腾讯云后台会对上传图做预检，失败时返回类似 {"Error":{"Code":"InvalidParameterValue.ImageIllegal","Message":"图片不符合要求"}} 的错误，但不说明具体哪条违规。
已验证的关键限制：
- 人脸必须正向、居中、无遮挡 —— 侧脸、低头、戴口罩大概率被拒
- 图片尺寸不能超过
2MB，且宽高均需在100–2000px范围内 - 必须是 RGB 模式，CMYK 或带 alpha 通道的 PNG 可能触发
ImageIllegal -
model参数填的贴纸 ID（如ff_10001）必须已在控制台「人脸融合」服务中启用并发布，未发布会返回ResourceNotFound
性能影响：每次请求都会触发云端人脸检测 + 关键点定位 + 融合渲染，平均耗时 800ms–2s，不适合高频实时场景（比如视频流帧处理）。如需批量处理，务必加限流，避免触发频率限制（默认 10 QPS）。
PHP 里没现成轮子，但可复用腾讯云通用签名逻辑
虽然没人维护 facefusion 的 PHP 封装，但你可以抄腾讯云官方 GitHub 上 tencentcloud-sdk-php 里 TencentCloud\Common\Signature 类的签名逻辑，只替换 Service 和 endpoint 即可。
关键差异点：
- endpoint 是
https://facefusion.tencentcloudapi.com，不是iai.tencentcloudapi.com - API 版本固定为
2018-07-09（注意不是 IAI 的2020-03-03） - 请求体里
image字段必须是CURLFile实例（PHP 5.5+），不能是字符串路径
示例片段（非完整）：
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://facefusion.tencentcloudapi.com');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'image' => new CURLFile('/path/to/photo.jpg'),
'model' => 'ff_10001',
'rfu' => 0.8
]);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: '.$authHeader,
'X-TC-Action: FaceFusion',
'X-TC-Version: 2018-07-09',
'X-TC-Region: ap-shanghai'
]);
真正麻烦的不是调用本身，而是签名字符串构造里对参数排序、URI 编码、换行符（\n）和空格的敏感度 —— 差一个字符，Authorization 就失效。建议第一次调试时，把生成的 StringToSign 打印出来，和 API Explorer 生成的逐字比对。
