volcengine-video-understanding

Original：🇨🇳 Chinese

Translated

1 scriptsChecked / no sensitive code detected

Volcengine Video Understanding - Analyze video content using Volcano Ark Video Understanding API. Upload videos via Files API (recommended), supports large files up to 512MB, applicable for video content analysis, object recognition, action understanding, etc. This skill is activated when users need to analyze videos, understand video content, or extract video information.

2installs

Sourcefreestylefly/canghe-skills

Added on2026-03-02

NPX Install

npx skill4agent add freestylefly/canghe-skills volcengine-video-understanding

SKILL.md Content (Chinese)

View Translation Comparison →

Volcengine Video Understanding

Uses ByteDance Volcano Ark Video Understanding API (models such as doubao-seed-2-0-pro-260215) to conduct in-depth understanding and analysis of videos.

Recommended method: Files API upload + Responses API analysis

Supports video files up to 512MB
Automatic video preprocessing (FPS sampling)
Files can be reused (stored for 7 days)

Features

Video Upload: Upload local videos via Files API (recommended, max 512MB)
Content Understanding: Analyze video scenes, characters, actions, emotions
Video Q&A: Answer user questions based on video content
Video Description: Automatically generate video descriptions and summaries

Prerequisites

The

ARK_API_KEY

environment variable needs to be set.

Configuration Method (Recommended)

Copy the configuration template:

bash

cp .canghe-skills/.env.example .canghe-skills/.env

Edit the
```
.canghe-skills/.env
```
file and fill in your API Key:

ARK_API_KEY=your-actual-api-key-here

Or use environment variables

bash

export ARK_API_KEY="your-api-key"

Loading Priority

System environment variable (
```
process.env
```
)
```
.canghe-skills/.env
```
in current directory
```
~/.canghe-skills/.env
```
in user home directory

Usage

1. Basic Video Analysis (Files API method - Recommended)

bash

cd ~/.openclaw/workspace/skills/volcengine-video-understanding
python3 scripts/video_understand.py /path/to/video.mp4 "Describe the content of this video"

2. Video Q&A

bash

python3 scripts/video_understand.py /path/to/video.mp4 "What characters appear in the video?"

3. Sentiment Analysis

bash

python3 scripts/video_understand.py /path/to/video.mp4 "Analyze the emotional changes of the characters in the video"

4. Specify Model and Frame Rate

bash

python3 scripts/video_understand.py /path/to/video.mp4 "Summarize the key points of the video" \
  --model doubao-seed-2-0-pro-260215 \
  --fps 2

5. Save Results to File

bash

python3 scripts/video_understand.py /path/to/video.mp4 "Describe the video" --output result.json

Parameter Description

Parameter	Default Value	Description
`video_path`	Required	Video file path
`instruction`	Required	Analysis instruction/question
`--model`	doubao-seed-2-0-pro-260215	Model ID
`--fps`	1	Video sampling frame rate (preprocessing)
`--output`	-	Result output file path

Supported Models

```
doubao-seed-2-0-pro-260215
```
(default)
```
doubao-seed-2-0-lite-250728
```
```
doubao-seed-1-6-251015
```
Other Seed series video understanding models

Analysis Examples

Example 1: Video Content Description

bash

python3 scripts/video_understand.py ~/Desktop/video.mp4 "Describe the content of this video in detail, including scenes, characters and actions"

Example 2: Video Summary

bash

python3 scripts/video_understand.py ~/Desktop/video.mp4 "Summarize the key points of this video in 3 sentences"

Example 3: Action Recognition

bash

python3 scripts/video_understand.py ~/Desktop/video.mp4 "What actions are the characters in the video doing? Describe in chronological order"

Example 4: Scene Analysis

bash

python3 scripts/video_understand.py ~/Desktop/video.mp4 "Analyze the scene changes and environmental characteristics in the video"

Technical Details

Call Process

Upload Video: Upload local video file via Files API, specify FPS preprocessing configuration
Wait for Processing: Wait for video preprocessing to complete (status changes to processed)
Create Task: Call Responses API for video understanding
Get Results: Return analysis results

API Format

Files API Upload:

bash

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 Analysis:

json

{
  "model": "doubao-seed-2-0-pro-260215",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_video",
          "file_id": "file-xxxx"
        },
        {
          "type": "input_text",
          "text": "User instruction"
        }
      ]
    }
  ]
}

FPS Setting Recommendations

FPS	Applicable Scenarios
0.3-0.5	Slow-paced videos, static scenes, token saving
1	General video analysis (default)
2-3	Fast actions, detail analysis

Limitations

Video Format: MP4 (recommended), MOV, AVI
File Size: Max 512MB (Files API method)
Storage Time: Uploaded files are stored for 7 days by default
Processing Time: Usually 10-60 seconds depending on video length and complexity

Python API Usage

python

from scripts.video_understand import analyze_video

result = analyze_video(
    file_path="/path/to/video.mp4",
    instruction="Describe video content",
    model="doubao-seed-2-0-pro-260215",
    fps=1
)

# Extract answer
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)

Error Handling

Common errors and solutions:

Error	Cause	Solution
API Key error	Not set or incorrect	Check ARK_API_KEY environment variable
File does not exist	Wrong path	Check file path
Upload failed	File too large or format not supported	Check file size (<512MB) and format
Processing timeout	Video too long or complex	Shorten video or reduce FPS

volcengine-video-understanding

NPX Install

Tags

SKILL.md Content (Chinese)

Volcengine Video Understanding

Features

Prerequisites

Configuration Method (Recommended)

Or use environment variables

Loading Priority

Usage

1. Basic Video Analysis (Files API method - Recommended)

2. Video Q&A

3. Sentiment Analysis

4. Specify Model and Frame Rate

5. Save Results to File

Parameter Description

Supported Models

Analysis Examples

Example 1: Video Content Description

Example 2: Video Summary

Example 3: Action Recognition

Example 4: Scene Analysis

Technical Details

Call Process

API Format

FPS Setting Recommendations

Limitations

Python API Usage

Error Handling

Reference Documents