前言¶
做人脸与模板图融合时，常见做法是自己在项目里接腾讯云 FuseFaceUltra 接口、处理鉴权与参数，再让 Coding Agent 只能「写调用代码」而不能直接出图。若希望 Agent 在对话里拿到模板图和用户脸图后就能同步返回融合结果，需要把开通服务、密钥、脚本入口和模型类型选择写进可执行的 Skill 规范。
下面介绍 SkillHub 上的 TencentCloud Image Face Fusion（坐标 @tencent-adm/tencentcloud-image-face-fusion，版本 1.0.0）：由腾讯云智能创作团队发布，归类为 design-media，来源为 enterprise，并标注 requires_api_key=true。
这是什么¶
TencentCloud Image Face Fusion 是一个基于通用 SKILL.md 格式的 Agent Skill，封装腾讯云图片人脸融合（专业版）能力：将用户人脸与素材模板图中的人脸融合，通过同步接口 FuseFaceUltra（域名 facefusion.tencentcloudapi.com，版本 2022-09-27）返回结果。
SkillHub 页面简介与技能包内描述一致：支持自定义美颜、人脸增强、牙齿增强、拉脸等效果参数（对应 API 的 FusionUltraParam），最高支持 8K 分辨率（单边小于 8000 像素），并提供多种融合模型类型（SwapModelType 1–6）。
核心功能¶
经核对技能包与 API 参考文档，可确认的能力如下。
- 同步人脸融合：场景为「人脸融合（专业版）」，脚本为
scripts/main.py，返回方式为同步；图片限制为 base64 编码后 ≤10M，URL ≤20M。 - 输入方式：
--model为素材模板图，--face为用户人脸图，均支持 URL 或本地路径。 - 模型类型：
--swap-model-type可选 1–6，覆盖泛娱乐、影视自然/高清、证件照、闭眼遮挡友好、电商/文旅等高相似度场景；默认 1。 - 合规标识：
--logo-add控制是否在结果图添加 AI 合成标识（0 不添加，1 添加，默认 1）。 - 进阶 API 参数：通过
FusionUltraParam可配置拉脸（WarpRadio）、人脸增强（EnhanceRadio）、磨皮（MpRadio）、牙齿增强（TeethEnhanceRadio）、妆容迁移（MakeupTransferRadio）等；模板图最多支持融合 6 张人脸（MergeInfos）。 - Agent 执行约定：安装后 Skill 要求 Agent 在用户已提供模板图与人脸图且意图为融合时直接执行脚本，失败时返回错误说明，不得用模型自行「编造」融合图。
安装与启用¶
方式一：SkillHub CLI¶
先确认本机是否已有 skillhub（安装说明见 SkillHub 安装文档）：
command -v skillhub && skillhub --version
未安装时可按官方文档执行完整安装或仅 CLI 安装，例如：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装技能时必须用 --dir 指向当前 Agent 的 skills 目录。常用路径包括：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
示例（将 <skills 目录> 替换为实际路径）：
skillhub install @tencent-adm/tencentcloud-image-face-fusion --dir <skills 目录>
方式二：让 AI 按官方提示安装¶
SkillHub 技能页给出的提示为：根据 https://skillhub.cn/install/skillhub.md，安装 @tencent-adm/tencentcloud-image-face-fusion。
密钥与环境变量¶
- 在 腾讯云人脸融合控制台 开通服务。
- 在 API 密钥管理 获取
SecretId与SecretKey。 - 设置环境变量（Linux / macOS 示例）：
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
技能包要求勿将密钥硬编码进代码。运行 main.py 依赖 Python 3.7+ 与 tencentcloud-sdk-python（脚本可自动安装依赖）。
典型用法¶
安装并配置密钥后，Agent 应按 Skill 内规范调用 main.py。命令形式如下（<SKILL_DIR> 为技能安装目录）：
python3 <SKILL_DIR>/scripts/main.py --model "<MODEL_PIC_INPUT>" --face "<USER_FACE_INPUT>" [--swap-model-type <1-6>] [--logo-add <0|1>]
技能包中的可复现示例：
# 基本用法：素材模板图 + 用户人脸图（URL）
python3 /path/to/scripts/main.py --model "https://example.com/template.png" --face "https://example.com/user_face.png"
# 证件照等场景：影视级高清、高人脸相似度
python3 /path/to/scripts/main.py --model "/path/to/template.jpg" --face "/path/to/face.jpg" --swap-model-type 4
# 不添加 AI 合成标识
python3 /path/to/scripts/main.py --model "https://example.com/template.png" --face "https://example.com/face.png" --logo-add 0
成功时脚本输出 JSON，其中 FusedImage 为结果图 URL（或 base64，取决于 API 的 RspImgType）；URL 有效期为 1 天。更完整的字段与错误码见技能内 references/FuseFaceUltraApi.md，对应腾讯云文档 图片人脸融合（专业版）。
在 Cursor 等客户端中，也可直接用自然语言描述需求（提供模板图与人脸图路径或 URL、是否需要特定 swap-model-type），由 Agent 读取已安装的 SKILL.md 后执行上述命令。
适用场景与注意¶
适合谁：需要在设计/媒体类 Agent 工作流里做人脸模板融合、且希望走腾讯云官方接口与计费体系的团队；SkillHub 上该技能评分 100000，下载约 1949 次、安装约 41 次（数据以 SkillHub 页面统计为准）。
使用注意：
- 必须配置腾讯云 API 密钥；未开通人脸融合服务会导致调用失败。
- 图片格式为 jpg/png，面部与分辨率需满足 API 文档中的最小/最大边长要求。
SwapModelType6 与部分FusionUltraParam的适用范围以 API 文档为准（例如部分参数仅对类型 1–5 生效）。- 融合失败时 Agent 应如实报错，不应改用大模型生成替代图。
结尾¶
TencentCloud Image Face Fusion 把腾讯云图片人脸融合（专业版）的同步调用、模型选择与合规标识写进 Agent 可执行的 Skill，减少重复对接 FuseFaceUltra 的成本。官方入口：https://api.skillhub.cn/tencent-adm/tencentcloud-image-face-fusion；SkillHub 展示页：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-image-face-fusion。
