tencentcloud-vita（腾讯云 vita）

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 必须可公开访问。
• 本地图片：可直接调用脚本；脚本会读取文件并转为 base64 data URL 后调用 VITA API。
• 本地视频：当前脚本不直接支持上传；如需分析，需先借助其他上传工具（如 COS 相关 skill）上传并获得可访问 URL，再传给脚本。
• 能力边界：当前脚本不内置 COS 上传能力。

Agent 执行指令（必读）

ℹ️ 本节是 Agent 的核心执行规范。当用户明确请求进行图片理解、视频理解、图像分析、视频分析，或设置 vita prompt 时，Agent 应按以下规则执行。

🔑 通用执行规则

1. 触发条件：用户提供图片或视频，且意图为视觉内容理解 / 分析；或用户希望自定义、设置、更新 vita prompt。
2. ⛔ 禁止替代：VITA 脚本调用失败时，Agent 严禁自行编造分析结果，必须返回清晰错误说明。
3. 输入处理：遵循上文"输入与媒体处理规则"；其中本地视频如需继续处理，应先上传为可访问 URL。

📌 设置自定义 Prompt（持久化）

触发条件：用户表达"设置 / 更新 VITA prompt"意图，例如：

• "设置视频理解 prompt 为..."
• "设置 vita prompt: ..."
• "设置视频理解的提示词: ..."
• "更新 vita prompt 为..."

执行方式：Agent 直接将用户指定的 prompt 写入以下文件（无需调用脚本）：

<SKILL_DIR>/prompt/vita_prompt.txt

• 文件不存在则创建并写入。
• 文件已存在则覆盖为新的 prompt。
• 写入完成后，向用户确认保存成功，并展示保存内容。

💡 Prompt 优先级说明

脚本中 prompt 的使用优先级从高到低为：

1. 命令行参数 --prompt：用户显式传入的 prompt，优先级最高。
2. 持久化 Prompt 文件：<SKILL_DIR>/prompt/vita_prompt.txt 中保存的自定义 prompt。
3. 默认 Prompt：内置默认值 请描述这段媒体内容。

即：如果用户未传 --prompt，脚本会自动尝试读取持久化文件；如果文件不存在或为空，则使用默认值。

📌 调用流程

Step 0: 本地视频处理（仅当用户提供本地视频时执行）

当输入是本地视频路径，而不是以 http:// 或 https:// 开头的 URL 时，Agent 可先借助单独上传工具（如 COS 相关 skill）上传视频，获取可访问 URL 后，再将该 URL 作为 Step 1 的输入。

注意事项：

1. 这一步不是当前 scripts/main.py 的内置能力，而是 Agent 可选的编排流程。
2. 上传能力、鉴权配置、Bucket / Region 等由对应上传工具自行管理。
3. 如果没有可用上传工具或环境未配置完成，Agent 应明确告知用户当前脚本无法直接处理本地视频。

Step 1: 发起 API 调用

python3 <SKILL_DIR>/scripts/main.py --image "<IMAGE_URL_OR_LOCAL_PATH>" --prompt "<PROMPT>"

python3 <SKILL_DIR>/scripts/main.py --video "<VIDEO_URL>" --prompt "<PROMPT>"

📌 参数说明

📤 输出格式

非流式输出（默认）：

{
  "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 安装）
• 环境变量

- TENCENTCLOUD_VITA_API_KEY：TencentCloud VITA 接口 API Key

获取 TencentCloud VITA API KEY

1. 登录腾讯云控制台：https://console.cloud.tencent.com/tiia/vita-service-management
2. 首次使用需"确认开通服务"
3. 点击"创建 API KEY"生成密钥
4. 点击"查看"复制 API KEY

设置环境变量

Linux / macOS：

export TENCENTCLOUD_VITA_API_KEY="your_api_key_here"

Windows (PowerShell)：

$env:TENCENTCLOUD_VITA_API_KEY = "your_api_key_here"

调用示例

# Single image understanding (remote URL) — TencentCloud VITA image analysis
python3 <SKILL_DIR>/scripts/main.py \
  --image "https://example.com/image.jpg" \
  --prompt "描述这张图片中的内容"

# Single image understanding (local file, auto-converted to base64 data URL)
python3 <SKILL_DIR>/scripts/main.py \
  --image "./demo.png" \
  --prompt "描述这张图片中的内容"

# Multi-image sequential analysis — vita multi-frame understanding
python3 <SKILL_DIR>/scripts/main.py \
  --image "https://example.com/frame1.jpg" \
  --image "./frame2.png" \
  --image "https://example.com/frame3.jpg" \
  --prompt "分析这些图片中发生了什么变化"

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

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

# Low-temperature output for deterministic image analysis
python3 <SKILL_DIR>/scripts/main.py \
  --image "https://example.com/chart.png" \
  --prompt "提取图表中的数据" \
  --temperature 0.1

# stdin JSON mode — VITA API via piped input
echo '{"media":[{"type":"video","url":"https://example.com/video.mp4"}],"prompt":"分析视频"}' \
  | python3 <SKILL_DIR>/scripts/main.py --stdin

Prompt 模板推荐

根据使用场景选择合适的 prompt，充分发挥 TencentCloud VITA 的 video understanding 与图像理解能力：

监控视频分析（Surveillance Video Understanding）：

你是一个视频事件摘要专家。分析视频内容，以JSON格式输出：{"description":"一句话描述","title":"标题","object":["对象"],"event":["事件序列"]}

新闻视频解读（News Video Understanding）：

你是专业新闻分析师，基于视频核心信息，生成：①标题（3个风格选项）②事件核心概述③关键细节④影响与延伸⑤信息来源

带货商品讲解（Product Demo Video Analysis）：

观看带货视频，提取：商品名称、应用场景、核心卖点，并按营销阶段（时间范围、画面描述、语音内容、景别、营销意图）划分视频结构

体育高光时刻（Sports Highlight Extraction）：

以专业体育解说视角，捕捉视频中的得分、高光、犯规、特写片段，输出：片段编号、时间范围（含关键帧）、景别、情景描述、画面文字

直播质量评分（Live Stream Quality Assessment）：

从6个维度评估直播片段：①直播间环境②主播语言③主播形象④出镜状态⑤互动引导⑥礼貌热情，每项输出是/否及判断依据

费用说明

默认并发为 5，超出会返回 429 错误。

核心脚本

• scripts/main.py — TencentCloud VITA 图像与视频理解脚本，支持单图、多图、视频URL，支持流式 / 非流式输出；本地图片会自动转为 base64，本地视频不直接支持。