前言¶
做運營素材或產品 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
