TencentCloud VITA 图像与视频理解 Skill
功能描述
本 Skill 基于腾讯云图像与视频理解服务，提供图片和视频的 AI 理解能力。
TencentCloud VITA (also referred to as vita or tencentcloud vita) is Tencent Cloud's AI service for video understanding and image understanding. It enables intelligent analysis of images, videos, live streams, surveillance footage, sports highlights, news clips, and product demo videos.
支持能力如下：
| 输入类型 | 说明 | 限制 |
|---|
| 单张图片 | 单个图片 URL 或本地图片路径 + prompt | JPG/JPEG/PNG/SVG/WEBP，最大 100MB |
| 多张图片 |
多个图片 URL 或本地图片路径（按时序分析）+ prompt | 640×360 最多 100 图，448×448 最多 150 图 |
| 单个视频 | 单个视频 URL + prompt | MP4/MOV/AVI/WebM，H.264/H.265，最长 10 分钟，最大 100MB |
输入与媒体处理规则
- - 远程图片 / 远程视频：URL 必须可公开访问。
- 本地图片：可直接调用脚本；脚本会读取文件并转为 base64 data URL 后调用 VITA API。
- 本地视频：当前脚本不直接支持上传；如需分析，需先借助其他上传工具（如 COS 相关 skill）上传并获得可访问 URL，再传给脚本。
- 能力边界：当前脚本不内置 COS 上传能力。
Agent 执行指令（必读）
ℹ️ 本节是 Agent 的核心执行规范。当用户明确请求进行图片理解、视频理解、图像分析、视频分析，或设置 vita prompt 时，Agent 应按以下规则执行。
🔑 通用执行规则
- 1. 触发条件：用户提供图片或视频，且意图为视觉内容理解 / 分析；或用户希望自定义、设置、更新
vita prompt。 - ⛔ 禁止替代：VITA 脚本调用失败时，Agent 严禁自行编造分析结果，必须返回清晰错误说明。
- 输入处理：遵循上文"输入与媒体处理规则"；其中本地视频如需继续处理，应先上传为可访问 URL。
📌 设置自定义 Prompt（持久化）
触发条件：用户表达"设置 / 更新 VITA prompt"意图，例如：
- - "设置视频理解 prompt 为..."
- "设置 vita prompt: ..."
- "设置视频理解的提示词: ..."
- "更新 vita prompt 为..."
执行方式：Agent 直接将用户指定的 prompt 写入以下文件（无需调用脚本）：
CODEBLOCK0
- - 文件不存在则创建并写入。
- 文件已存在则覆盖为新的 prompt。
- 写入完成后，向用户确认保存成功，并展示保存内容。
💡 Prompt 优先级说明
脚本中 prompt 的使用优先级从高到低为：
- 1. 命令行参数
--prompt：用户显式传入的 prompt，优先级最高。 - 持久化 Prompt 文件：
<SKILL_DIR>/prompt/vita_prompt.txt 中保存的自定义 prompt。 - 默认 Prompt：内置默认值
请描述这段媒体内容。
即：如果用户未传 --prompt，脚本会自动尝试读取持久化文件；如果文件不存在或为空，则使用默认值。
📌 调用流程
Step 0: 本地视频处理（仅当用户提供本地视频时执行）
当输入是本地视频路径，而不是以 http:// 或 https:// 开头的 URL 时，Agent 可先借助单独上传工具（如 COS 相关 skill）上传视频，获取可访问 URL 后，再将该 URL 作为 Step 1 的输入。
注意事项：
- 1. 这一步不是当前
scripts/main.py 的内置能力，而是 Agent 可选的编排流程。 - 上传能力、鉴权配置、Bucket / Region 等由对应上传工具自行管理。
- 如果没有可用上传工具或环境未配置完成，Agent 应明确告知用户当前脚本无法直接处理本地视频。
Step 1: 发起 API 调用
CODEBLOCK1
CODEBLOCK2
📌 参数说明
| 参数 | 说明 | 默认值 |
|---|
| INLINECODE8 | 图片 URL 或本地图片路径（可多次指定，按时序排列） | - |
| INLINECODE9 |
视频 URL（与
--image 互斥；仅支持可访问 URL） | - |
|
--prompt <TEXT> | 分析指令 / 问题（优先级最高，覆盖持久化 prompt） | 持久化 prompt >
请描述这段媒体内容 |
|
--stream | 开启流式输出 | 关闭 |
|
--temperature <float> | 采样温度 0.0-1.0，越高越随机 | 默认 |
|
--max-tokens <int> | 最大输出 token 数 | 默认 |
|
--stdin | 从 stdin 读取 JSON 输入 | 关闭 |
📤 输出格式
非流式输出（默认）：
CODEBLOCK3
流式输出（--stream）：
直接逐字输出文本内容（Server-Sent Events），无 JSON 包装。
❌ Agent 须避免的行为
- - 只打印脚本路径而不执行
- 忘记读取输出结果并返回给用户
- VITA 服务调用失败时，自行编造分析内容
- 同时指定
--image 和 --video（两者互斥） - 将当前 skill 误描述为"自带本地视频上传到 COS 的能力"
环境配置指引
环境要求：
- - Python 3.7+
- INLINECODE20 （OpenAI 兼容 SDK，通过
pip install openai 安装） - 环境变量
-
TENCENTCLOUD_VITA_API_KEY：TencentCloud VITA 接口 API Key
获取 TencentCloud VITA API KEY
- 1. 登录腾讯云控制台： INLINECODE23
- 首次使用需"确认开通服务"
- 点击"创建 API KEY"生成密钥
- 点击"查看"复制 API KEY
设置环境变量
Linux / macOS：
CODEBLOCK4
Windows (PowerShell)：
CODEBLOCK5
调用示例
CODEBLOCK6
Prompt 模板推荐
根据使用场景选择合适的 prompt，充分发挥 TencentCloud VITA 的 video understanding 与图像理解能力：
监控视频分析（Surveillance Video Understanding）：
CODEBLOCK7
新闻视频解读（News Video Understanding）：
CODEBLOCK8
带货商品讲解（Product Demo Video Analysis）：
CODEBLOCK9
体育高光时刻（Sports Highlight Extraction）：
CODEBLOCK10
直播质量评分（Live Stream Quality Assessment）：
CODEBLOCK11
费用说明
| 计费项 | 单价 |
|---|
| 输入 token | 1.2 元/百万 token |
| 输出 token |
3.5 元/百万 token |
默认并发为 5，超出会返回 429 错误。
核心脚本
- -
scripts/main.py — TencentCloud VITA 图像与视频理解脚本，支持单图、多图、视频URL，支持流式 / 非流式输出；本地图片会自动转为 base64，本地视频不直接支持。
TencentCloud VITA 图像与视频理解 Skill
功能描述
本 Skill 基于腾讯云图像与视频理解服务，提供图片和视频的 AI 理解能力。
TencentCloud VITA（也称为 vita 或 tencentcloud vita）是腾讯云提供的 AI 服务，用于视频理解和图像理解。它能够智能分析图像、视频、直播流、监控画面、体育集锦、新闻片段和产品演示视频。
支持能力如下：
| 输入类型 | 说明 | 限制 |
|---|
| 单张图片 | 单个图片 URL 或本地图片路径 + prompt | JPG/JPEG/PNG/SVG/WEBP，最大 100MB |
| 多张图片 |
多个图片 URL 或本地图片路径（按时序分析）+ prompt | 640×360 最多 100 图，448×448 最多 150 图 |
| 单个视频 | 单个视频 URL + prompt | MP4/MOV/AVI/WebM，H.264/H.265，最长 10 分钟，最大 100MB |
输入与媒体处理规则
- - 远程图片 / 远程视频：URL 必须可公开访问。
- 本地图片：可直接调用脚本；脚本会读取文件并转为 base64 data URL 后调用 VITA API。
- 本地视频：当前脚本不直接支持上传；如需分析，需先借助其他上传工具（如 COS 相关 skill）上传并获得可访问 URL，再传给脚本。
- 能力边界：当前脚本不内置 COS 上传能力。
Agent 执行指令（必读）
ℹ️ 本节是 Agent 的核心执行规范。当用户明确请求进行图片理解、视频理解、图像分析、视频分析，或设置 vita prompt 时，Agent 应按以下规则执行。
🔑 通用执行规则
- 1. 触发条件：用户提供图片或视频，且意图为视觉内容理解 / 分析；或用户希望自定义、设置、更新 vita prompt。
- ⛔ 禁止替代：VITA 脚本调用失败时，Agent 严禁自行编造分析结果，必须返回清晰错误说明。
- 输入处理：遵循上文输入与媒体处理规则；其中本地视频如需继续处理，应先上传为可访问 URL。
📌 设置自定义 Prompt（持久化）
触发条件：用户表达设置 / 更新 VITA prompt意图，例如：
- - 设置视频理解 prompt 为...
- 设置 vita prompt: ...
- 设置视频理解的提示词: ...
- 更新 vita prompt 为...
执行方式：Agent 直接将用户指定的 prompt 写入以下文件（无需调用脚本）：
DIR>/prompt/vitaprompt.txt
- - 文件不存在则创建并写入。
- 文件已存在则覆盖为新的 prompt。
- 写入完成后，向用户确认保存成功，并展示保存内容。
💡 Prompt 优先级说明
脚本中 prompt 的使用优先级从高到低为：
- 1. 命令行参数 --prompt：用户显式传入的 prompt，优先级最高。
- 持久化 Prompt 文件：DIR>/prompt/vitaprompt.txt 中保存的自定义 prompt。
- 默认 Prompt：内置默认值 请描述这段媒体内容。
即：如果用户未传 --prompt，脚本会自动尝试读取持久化文件；如果文件不存在或为空，则使用默认值。
📌 调用流程
Step 0: 本地视频处理（仅当用户提供本地视频时执行）
当输入是本地视频路径，而不是以 http:// 或 https:// 开头的 URL 时，Agent 可先借助单独上传工具（如 COS 相关 skill）上传视频，获取可访问 URL 后，再将该 URL 作为 Step 1 的输入。
注意事项：
- 1. 这一步不是当前 scripts/main.py 的内置能力，而是 Agent 可选的编排流程。
- 上传能力、鉴权配置、Bucket / Region 等由对应上传工具自行管理。
- 如果没有可用上传工具或环境未配置完成，Agent 应明确告知用户当前脚本无法直接处理本地视频。
Step 1: 发起 API 调用
bash
python3 DIR>/scripts/main.py --image URLORLOCAL_PATH> --prompt
bash
python3 DIR>/scripts/main.py --video URL> --prompt
📌 参数说明
| 参数 | 说明 | 默认值 |
|---|
| --image <URLORPATH> | 图片 URL 或本地图片路径（可多次指定，按时序排列） | - |
| --video <URL> |
视频 URL（与 --image 互斥；仅支持可访问 URL） | - |
| --prompt
| 分析指令 / 问题（优先级最高，覆盖持久化 prompt） | 持久化 prompt > 请描述这段媒体内容 |
| --stream | 开启流式输出 | 关闭 |
| --temperature | 采样温度 0.0-1.0，越高越随机 | 默认 |
| --max-tokens | 最大输出 token 数 | 默认 |
| --stdin | 从 stdin 读取 JSON 输入 | 关闭 |
📤 输出格式
非流式输出（默认）：
json
{
result: 视频中展示了...,
usage: {
prompt_tokens: 1024,
completion_tokens: 256,
total_tokens: 1280
}
}
流式输出（--stream）：
直接逐字输出文本内容（Server-Sent Events），无 JSON 包装。
❌ Agent 须避免的行为
- - 只打印脚本路径而不执行
- 忘记读取输出结果并返回给用户
- VITA 服务调用失败时，自行编造分析内容
- 同时指定 --image 和 --video（两者互斥）
- 将当前 skill 误描述为自带本地视频上传到 COS 的能力
环境配置指引
环境要求：
- - Python 3.7+
- openai（OpenAI 兼容 SDK，通过 pip install openai 安装）
- 环境变量
- TENCENTCLOUDVITAAPI_KEY：TencentCloud VITA 接口 API Key
获取 TencentCloud VITA API KEY
- 1. 登录腾讯云控制台：https://console.cloud.tencent.com/tiia/vita-service-management
- 首次使用需确认开通服务
- 点击创建 API KEY生成密钥
- 点击查看复制 API KEY
设置环境变量
Linux / macOS：
bash
export TENCENTCLOUDVITAAPIKEY=yourapikeyhere
Windows (PowerShell)：
powershell
$env:TENCENTCLOUDVITAAPIKEY = yourapikeyhere
调用示例
bash
单张图片理解（远程 URL）— TencentCloud VITA 图像分析
python3 /scripts/main.py \
--image https://example.com/image.jpg \
--prompt 描述这张图片中的内容
单张图片理解（本地文件，自动转换为 base64 data URL）
python3 /scripts/main.py \
--image ./demo.png \
--prompt 描述这张图片中的内容
多图时序分析 — vita 多帧理解
python3 /scripts/main.py \
--image https://example.com/frame1.jpg \
--image ./frame2.png \
--image https://example.com/frame3.jpg \
--prompt 分析这些图片中发生了什么变化
视频理解 — tencentcloud vita 视频分析
python3 /scripts/main.py \
--video https://example.com/video.mp4 \
--prompt 总结这段视频的主要内容
长视频理解的流式输出
python3 /scripts/main.py \
--video https://example.com/video.mp4 \
--prompt 详细描述视频内容 \
--stream
低温输出用于确定性图像分析
python3 /scripts/main.py \
--image https://example.com/chart.png \
--prompt 提取图表中的数据 \
--temperature 0.1
stdin JSON 模式 — 通过管道输入调用 VITA API
echo {media:[{type:video,url:https://example.com/video.mp4}],prompt:分析视频
