volcengine-video-understanding
火山视频理解 - 使用火山方舟视频理解 API 分析视频内容。通过 Files API 上传视频（推荐），支持大文件（最大512MB），可用于视频内容分析、物体识别、动作理解等。当用户需要分析视频、理解视频内容、提取视频信息时激活此技能。
- Installs
- 574
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/freestylefly/canghe-skills --skill volcengine-video-understanding- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads volcengine-video-understanding automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
火山视频理解
使用字节跳动火山方舟视频理解 API（doubao-seed-2-0-pro-260215 等模型）对视频进行深度理解和分析。
推荐方式：Files API 上传 + Responses API 分析
- 支持最大 512MB 视频文件
- 自动视频预处理（FPS采样）
- 文件可重复使用（存储7天）
功能
- 视频上传：通过 Files API 上传本地视频（推荐，最大512MB）
- 内容理解：分析视频场景、人物、动作、情感
- 视频问答：基于视频内容回答用户问题
- 视频描述：自动生成视频描述和摘要
前置要求
需要设置 ARK_API_KEY 环境变量。
配置方式（推荐）
- 复制配置模板：
cp .canghe-skills/.env.example .canghe-skills/.env
- 编辑
.canghe-skills/.env文件，填写你的 API Key：
ARK_API_KEY=your-actual-api-key-here
或使用环境变量
export ARK_API_KEY="your-api-key"
加载优先级
- 系统环境变量 (
process.env) - 当前目录
.canghe-skills/.env - 用户主目录
~/.canghe-skills/.env
使用方法
1. 基础视频分析（Files API 方式 - 推荐）
cd ~/.openclaw/workspace/skills/volcengine-video-understanding
python3 scripts/video_understand.py /path/to/video.mp4 "描述这个视频的内容"
2. 视频问答
python3 scripts/video_understand.py /path/to/video.mp4 "视频中出现了哪些人物？"
3. 情感分析
python3 scripts/video_understand.py /path/to/video.mp4 "分析视频中人物的情感变化"
4. 指定模型和帧率
python3 scripts/video_understand.py /path/to/video.mp4 "总结视频要点" \
--model doubao-seed-2-0-pro-260215 \
--fps 2
5. 保存结果到文件
python3 scripts/video_understand.py /path/to/video.mp4 "描述视频" --output result.json
参数说明
| 参数 | 默认值 | 说明 |
|---|---|---|
video_path | 必填 | 视频文件路径 |
instruction | 必填 | 分析指令/问题 |
--model | doubao-seed-2-0-pro-260215 | 模型 ID |
--fps | 1 | 视频采样帧率（预处理） |
--output | - | 结果输出文件路径 |
支持的模型
doubao-seed-2-0-pro-260215(默认)doubao-seed-2-0-lite-250728doubao-seed-1-6-251015- 其他 Seed 系列视频理解模型
分析示例
示例 1：视频内容描述
python3 scripts/video_understand.py ~/Desktop/video.mp4 "详细描述这个视频的内容，包括场景、人物和动作"
示例 2：视频摘要
python3 scripts/video_understand.py ~/Desktop/video.mp4 "用3句话总结这个视频的要点"
示例 3：动作识别
python3 scripts/video_understand.py ~/Desktop/video.mp4 "视频中的人物在做什么动作？按时间顺序描述"
示例 4：场景分析
python3 scripts/video_understand.py ~/Desktop/video.mp4 "分析视频中的场景变化和环境特征"
技术细节
调用流程
- 上传视频：通过 Files API 上传本地视频文件，指定 FPS 预处理配置
- 等待处理：等待视频预处理完成（状态变为 processed）
- 创建任务：调用 Responses API 进行视频理解
- 获取结果：返回分析结果
API 格式
Files API 上传：
curl https://ark.cn-beijing.volces.com/api/v3/files \
-H "Authorization: Bearer $ARK_API_KEY" \
-F 'purpose=user_data' \
-F 'file=@video.mp4' \
-F 'preprocess_configs[video][fps]=1'
Responses API 分析：
{
"model": "doubao-seed-2-0-pro-260215",
"input": [
{
"role": "user",
"content": [
{
"type": "input_video",
"file_id": "file-xxxx"
},
{
"type": "input_text",
"text": "用户指令"
}
]
}
]
}
FPS 设置建议
| FPS | 适用场景 |
|---|---|
| 0.3-0.5 | 慢节奏视频、静态场景、节省token |
| 1 | 一般视频分析（默认） |
| 2-3 | 快速动作、细节分析 |
限制
- 视频格式：MP4（推荐）、MOV、AVI
- 文件大小：最大 512MB（Files API 方式）
- 存储时间：上传的文件默认存储 7 天
- 处理时间：根据视频长度和复杂度，通常 10-60 秒
Python API 使用
from scripts.video_understand import analyze_video
result = analyze_video(
file_path="/path/to/video.mp4",
instruction="描述视频内容",
model="doubao-seed-2-0-pro-260215",
fps=1
)
# 提取回答
text = ""
for item in result.get("output", []):
if item.get("type") == "message":
for content in item.get("content", []):
if content.get("type") == "output_text":
text = content.get("text", "")
break
print(text)
错误处理
常见错误及解决方案：
| 错误 | 原因 | 解决方案 |
|---|---|---|
| API Key 错误 | 未设置或错误 | 检查 ARK_API_KEY 环境变量 |
| 文件不存在 | 路径错误 | 检查文件路径 |
| 上传失败 | 文件过大或格式不支持 | 检查文件大小（<512MB）和格式 |
| 处理超时 | 视频过长或复杂 | 缩短视频或降低 FPS |
参考文档
FAQ
What does the volcengine-video-understanding skill do?
火山视频理解 - 使用火山方舟视频理解 API 分析视频内容。通过 Files API 上传视频（推荐），支持大文件（最大512MB），可用于视频内容分析、物体识别、动作理解等。当用户需要分析视频、理解视频内容、提取视频信息时激活此技能。
How do I install volcengine-video-understanding?
Run npx skills add https://github.com/freestylefly/canghe-skills --skill volcengine-video-understanding in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/volcengine-video-understanding/ (personal) or .claude/skills/volcengine-video-understanding/ (project).
Which AI agents can use volcengine-video-understanding?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is volcengine-video-understanding safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains volcengine-video-understanding?
It is published by freestylefly in freestylefly/canghe-skills. It has 574 recorded installs.
More from freestylefly/canghe-skills
manga-drama
freestylefly/canghe-skills
漫剧生成器 - 基于 Seedance 的漫画风格短剧生成工具。支持以主角图片为基础，自动生成漫剧分镜脚本并生成视频。适用于创作漫画风格的短视频、角色故事、动画短片等。当用户想要生成漫画风格的视频短剧、角色故事或漫剧时使用此技能。
manga-style-video
freestylefly/canghe-skills
漫画风格视频生成器 - 专门生成日式治愈系、国风水墨、美式卡通等漫画风格的动画视频。内置8种漫画风格模板，支持图生视频，一键生成高质量漫画动画。当用户需要生成漫画风格、动画风格、手绘风格的视频时使用此技能。
seedance-video
freestylefly/canghe-skills
使用字节跳动 Seedance 模型生成视频。支持文生视频和图生视频功能，通过 volcengine-ark SDK 调用 API。当用户需要生成视频、创建视频内容或基于文字/图片制作视频时激活此技能。
canghe-image-gen
freestylefly/canghe-skills
AI image generation with OpenAI, Google, DashScope and Canghe APIs. Supports text-to-image, reference images, aspect ratios. Sequential by default; parallel generation available on request. Use when user asks to generate, create, or draw images.
canghe-comic
freestylefly/canghe-skills
Knowledge comic creator supporting multiple art styles and tones. Creates original educational comics with detailed panel layouts and sequential image generation. Use when user asks to create "知识漫画", "教育漫画", "biography comic", "tutorial comic", or "Logicomix-style comic".
canghe-xhs-images
freestylefly/canghe-skills
Generates Xiaohongshu (Little Red Book) infographic series with 10 visual styles and 8 layouts. Breaks content into 1-10 cartoon-style images optimized for XHS engagement. Use when user mentions "小红书图片", "XHS images", "RedNote infographics", "小红书种草", or wants social media infographics for Chinese platforms.
Popular media & creative skills
hyperframes
heygen-com/hyperframes
Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.
media-use
heygen-com/hyperframes
Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.
hyperframes-registry
heygen-com/hyperframes
About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.
hyperframes-creative
heygen-com/hyperframes
Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use hyperframes-animation.
ai-video-generation
101-skills/superpowers
Generate AI videos with Google Veo, Seedance 2.0, HappyHorse, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 2.0, HappyHorse 1.0, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, reference-to-video, video editing, lipsync, avatar animation, video upscaling, foley sound. Use for: social media videos, marketing content, explainer videos, product demos, AI avatars. Triggers: video generation, ai video, text to video, image to video, veo, animate image, video from image, ai animation, video generator, generate video, t2v, i2v, ai video maker, create video with ai, runway alternative, pika alternative, sora alternative, kling alternative, seedance, happyhorse
ai-image-generation
101-skills/superpowers
Generate AI images with GPT-Image-2, FLUX, Gemini, Grok, Seedream, Reve and 50+ models via inference.sh CLI. Models: GPT-Image-2, FLUX Dev LoRA, FLUX.2 Klein LoRA, Gemini 3 Pro Image, Grok Imagine, Seedream 4.5, Reve, ImagineArt. Capabilities: text-to-image, image-to-image, inpainting, LoRA, image editing, upscaling, text rendering. Use for: AI art, product mockups, concept art, social media graphics, marketing visuals, illustrations. Triggers: flux, image generation, ai image, text to image, stable diffusion, generate image, ai art, midjourney alternative, dall-e alternative, text2img, t2i, image generator, ai picture, create image with ai, generative ai, ai illustration, grok image, gemini image, gpt image, openai image, chatgpt image