前言¶
做运营素材或产品 Demo 时，常见需求是把一张人物照片做成带模板动效的短视频。自己接云 API 要处理抠像、异步任务、轮询和密钥配置；在 Agent 里让模型「画一段视频」又容易偏离真实服务能力。下面介绍 SkillHub 上的 TencentCloud Video Effects（@tencent-adm/tencentcloud-video-effects）：在对话里上传或指定图片、选定特效模板，由 Skill 调用腾讯云视频特效接口生成结果视频 URL。
这是什么¶
TencentCloud Video Effects 是腾讯云智能创作团队发布的企业来源 Skill（design-media 分类，当前版本 1.0.1）。它把「图片 + 特效模板 → 短视频」封装成 Agent 可执行的 SKILL.md 与 scripts/main.py，底层对应腾讯云 TemplateToVideo（提交任务 SubmitTemplateToVideoJob、查询任务 DescribeTemplateToVideoJob）。Skill 会识别图片中人体轮廓并完成抠像，再按模板生成动感画面。
官方入口：
- API 页：https://api.skillhub.cn/tencent-adm/tencentcloud-video-effects
- SkillHub 页：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-video-effects
核心功能¶
根据 Skill 包内文档，已核实的能力如下：
- 视频特效生成：传入模板名（如文档示例
hug）与图片 URL 或本地路径，异步提交任务并默认轮询至完成，输出ResultVideoUrl。 - 输入约束：单图 ≤10MB；格式支持 png、jpg、jpeg、webp、bmp、tiff（与腾讯云 API 说明一致）。
- 可调参数：分辨率（默认
360p，可选如720p、1080p）、是否添加 AI 生成标识（--logo-add）、是否加背景音乐（--bgm）、轮询间隔与超时、或--no-poll仅返回 JobId。 - 密钥与开通：标签
requires_api_key=true；需开通视频特效服务并配置TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY环境变量。
人体抠像与模板列表以腾讯云控制台与 视频特效模板列表 为准；不同模板对图片数量、清晰度与积分消耗可能不同。
安装与启用¶
1、安装 SkillHub CLI（若尚未安装）¶
先检查是否已有 CLI：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装文档执行完整安装：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
说明见：https://skillhub.cn/install/skillhub.md
2、安装本 Skill 到当前 Agent 的 skills 目录¶
安装时必须用 --dir 指向 Agent 实际读取的目录，否则默认落在 ./skills/ 可能不会被加载。常用路径示例：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
安装命令（与 skillhub search 输出一致）：
skillhub install tencentcloud-video-effects --namespace tencent-adm --dir ~/.cursor/skills
也可让 Agent 按官方提示安装：参考 https://skillhub.cn/install/skillhub.md，安装坐标 @tencent-adm/tencentcloud-video-effects。
安装后重启或刷新 Agent，使其加载新 Skill。
3、配置腾讯云密钥¶
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
不要将密钥写入仓库或 Skill 脚本。main.py 在缺少密钥时会以 JSON 形式报错并给出上述指引。
4、运行环境¶
- Python 3.7+
- 依赖
tencentcloud-sdk-python、requests；Skill 说明脚本会在缺失时尝试自动安装 SDK。
典型用法¶
Skill 要求 Agent 在用户已提供图片且意图为视频特效时直接执行脚本，不要用模型自行「编造」视频内容；失败时应返回明确错误。
在 Skill 安装目录下，将 <SKILL_DIR> 替换为实际路径（例如 ~/.cursor/skills/@tencent-adm/tencentcloud-video-effects）。
基本调用（默认分辨率与轮询）：
python3 <SKILL_DIR>/scripts/main.py hug "https://example.com/human.png"
指定 720p 与背景音乐：
python3 <SKILL_DIR>/scripts/main.py hug "https://example.com/human.png" --resolution 720p --bgm
本地图片、关闭 AI 标识、1080p：
python3 <SKILL_DIR>/scripts/main.py hug /path/to/local/image.jpg --logo-add 0 --resolution 1080p
只提交任务、不等待结果：
python3 <SKILL_DIR>/scripts/main.py hug "https://example.com/human.png" --no-poll
成功时脚本输出 JSON，其中 ResultVideoUrl 为结果视频地址。查询接口文档注明该 URL 有效期 24 小时，落地业务时需自行下载或转存。
更细的 API 字段与错误码见 Skill 内 references/SubmitTemplateToVideoJob.md、references/DescribeTemplateToVideoJob.md，或腾讯云原文 119001、119002。
适用场景与注意¶
适合谁
- 已在 Cursor、Claude Code 等支持 Skills 的 Agent 中工作，希望用自然语言驱动「人像图 → 模板特效短视频」的开发者或内容同学。
- 愿意使用腾讯云视频特效计费与合规要求（含内容审核、AI 标识策略）的团队。
限制与注意
- 必须配置有效 API 密钥并完成服务开通；欠费、审核不通过、图片过大或 URL 不可访问会导致任务失败，错误码以 API 文档为准。
- 异步任务默认最长轮询 600 秒（可通过
--max-poll-time调整）；高并发可能触发JobNumExceed等限流。 --logo-add 0等功能可能需在控制台额外申请，以腾讯云控制台说明为准。- SkillHub 页面统计（截至资料抓取）：评分 100000，下载约 2003 次，安装约 38 次；enterprise 来源，发布者为腾讯云智能创作团队。
结尾¶
TencentCloud Video Effects 把腾讯云 TemplateToVideo 流程收敛成可安装的 Agent Skill：配置密钥后，用一条 main.py 命令即可完成提交、轮询与结果回传。若要在本地 Agent 中试用，可从官方 SkillHub 页获取安装说明：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-video-effects
