前言¶

做监控回放摘要、新闻片剪辑说明、或产品演示视频的要点提取时，常见做法是自己接多模态 API、写上传与鉴权、再拼 prompt。媒体格式、本地文件与公网 URL 的处理规则也容易在业务代码里散落。下面介绍 SkillHub 上的 TencentCloud VITA（坐标 @tencent-adm/tencentcloud-vita）：把腾讯云 VITA 的图像与视频理解能力封装成 Agent 可读的 SKILL.md 与 scripts/main.py，由 Agent 按规范调用脚本并回传结果，而不是在对话里「目测」编造分析。

这是什么¶

TencentCloud VITA 是腾讯云内容识别团队发布的企业来源 Skill（SkillHub 分类 design-media，当前版本 1.0.9）。它面向 图片理解、视频理解 及描述生成，官方简介中列出的场景包括：图像/视频分析、监控录像分析、体育高光提取、直播理解、新闻视频摘要、产品演示视频分析，以及设置或更新持久化的 vita prompt。

输入形态支持 单张图片、多张图片（按时序）、视频 URL；Skill 标签标明 requires_api_key=true，需配置腾讯云 VITA 的 API Key 后才能调用后端服务。

核心功能¶

以下能力均来自 Skill 包内 SKILL.md 与官方页面简介，可按输入类型对照使用。

媒体输入与限制¶

处理规则要点：

1. 远程图片、远程视频的 URL 须 可公开访问。
2. 本地图片可由脚本读取并转为 base64 data URL 后调用 API。
3. 本地视频脚本不直接上传；需先通过其他工具（如 COS 相关 Skill）得到可访问 URL，再传入 --video。
4. 调用失败时，Agent 规范要求 不得自行编造分析结果，应返回明确错误。

Prompt 与编排¶

• 用户可通过写入 <SKILL_DIR>/prompt/vita_prompt.txt 持久化自定义 prompt（无需跑脚本）。
• 运行时优先级：--prompt 参数 > 持久化文件 > 默认文案「请描述这段媒体内容」。
• 脚本支持非流式 JSON 输出、--stream 流式文本，以及 --stdin 读取 JSON。

依赖与环境¶

• Python 3.7+，pip install openai（OpenAI 兼容 SDK）。
• 环境变量 TENCENTCLOUD_VITA_API_KEY：在腾讯云控制台 VITA 服务管理 开通服务并创建 API KEY 后配置。

计费（Skill 文档记载）：输入 token 1.2 元/百万，输出 token 3.5 元/百万；默认并发 5，超出可能返回 429。

安装与启用¶

SkillHub 官方安装说明：先阅读 SkillHub 安装与优先源配置，再安装本 Skill。页面提供的安装坐标为 @tencent-adm/tencentcloud-vita。

使用 SkillHub CLI¶

未安装 CLI 时可执行完整安装（文档推荐）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安装 Skill 时 必须 用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能无法被识别：

skillhub install tencent-adm/tencentcloud-vita --dir <你的 Agent skills 目录>

常用目录（摘自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下 .agents/skills/

Zip 包安装¶

SkillHub 详情页提供 1.0.9 的 Zip 下载地址：

https://api.skillhub.cn/api/v1/download?slug=@tencent-adm/tencentcloud-vita

解压到上述 skills 目录对应子路径后，重启或刷新 Agent 即可加载。

配置 API Key¶

Linux / macOS 示例：

export TENCENTCLOUD_VITA_API_KEY="your_api_key_here"

Windows PowerShell：

$env:TENCENTCLOUD_VITA_API_KEY = "your_api_key_here"

典型用法¶

将 <SKILL_DIR> 替换为本 Skill 在本地 skills 目录中的实际路径（例如 ~/.cursor/skills/tencentcloud-vita）。

单张远程图片：

python3 <SKILL_DIR>/scripts/main.py \
  --image "https://example.com/image.jpg" \
  --prompt "描述这张图片中的内容"

本地图片（脚本自动转 base64）：

python3 <SKILL_DIR>/scripts/main.py \
  --image "./demo.png" \
  --prompt "描述这张图片中的内容"

多张图片按时序分析：

python3 <SKILL_DIR>/scripts/main.py \
  --image "https://example.com/frame1.jpg" \
  --image "./frame2.png" \
  --prompt "分析这些图片中发生了什么变化"

视频理解（仅 URL）：

python3 <SKILL_DIR>/scripts/main.py \
  --video "https://example.com/video.mp4" \
  --prompt "总结这段视频的主要内容"

流式长文本输出：

python3 <SKILL_DIR>/scripts/main.py \
  --video "https://example.com/video.mp4" \
  --prompt "详细描述视频内容" \
  --stream

非流式默认返回 JSON，包含 result 与 usage（token 统计）。--image 与 --video 互斥，不可同时指定。

Skill 内还提供了监控、新闻、带货、体育高光、直播质量等场景的 prompt 模板推荐，可按业务改写后写入 prompt/vita_prompt.txt 或通过 --prompt 传入。

适用场景与注意¶

适合谁：需要在 Cursor、Claude Code、Codex 等 Agent 工作流里统一接入腾讯云 VITA、且希望由 Skill 约束「必须跑脚本、禁止幻觉式视频描述」的团队；SkillHub 侧统计显示下载约 2171 次、安装约 141 次（页面数据，会随时间变化）。

需要注意：

1. 无 API Key 或 Key 无效时，脚本无法调用服务，应排查环境变量与控制台开通状态。
2. 本地视频必须先解决 公网 URL，本 Skill 不内置 COS 上传。
3. 图片体积、分辨率张数、视频时长与编码需满足上表限制，否则易在 API 层失败。
4. 企业来源 Skill，使用前可在 SkillHub 详情页查看安全扫描报告链接（页面展示 Keen、三不等相关结果）。

结尾¶

TencentCloud VITA Skill 把「图像/视频理解 + prompt 持久化 + 脚本调用约定」收拢到一套 Agent 可执行规范里，适合把 VITA 从零散脚本升级为可复用的 Skill 能力。官方入口：

• SkillHub 页面：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-vita
• API 坐标页：https://api.skillhub.cn/tencent-adm/tencentcloud-vita