canghe-volcengine-video-understanding

Name: canghe-volcengine-video-understanding
Author: freestylefly

415stars95forks

How to install canghe-volcengine-video-understanding?

freestylefly/canghe-skills/canghe-volcengine-video-understanding

$npx -y skills add freestylefly/canghe-skills --skill canghe-volcengine-video-understanding

Installs into the current project.

Summary

火山视频理解 - 使用火山方舟视频理解 API 分析视频内容。通过 Files API 上传视频（推荐），支持大文件（最大512MB），可用于视频内容分析、物体识别、动作理解等。当用户需要分析视频、理解视频内容、提取视频信息时激活此技能。

Files · 1

View on GitHub

SKILL.md

1	# 火山视频理解
2
3	使用字节跳动火山方舟视频理解 API（doubao-seed-2-0-pro-260215 等模型）对视频进行深度理解和分析。
4
5	推荐方式：Files API 上传 + Responses API 分析
6	- 支持最大 512MB 视频文件
7	- 自动视频预处理（FPS采样）
8	- 文件可重复使用（存储7天）
9
10	## 功能
11
12	- 视频上传：通过 Files API 上传本地视频（推荐，最大512MB）
13	- 内容理解：分析视频场景、人物、动作、情感
14	- 视频问答：基于视频内容回答用户问题
15	- 视频描述：自动生成视频描述和摘要
16
17	## 前置要求
18
19	需要设置 `ARK_API_KEY` 环境变量。
20
21	### 配置方式（推荐）
22
23	1. 复制配置模板：
24	```bash
25	cp .canghe-skills/.env.example .canghe-skills/.env
26	```
27
28	2. 编辑 `.canghe-skills/.env` 文件，填写你的 API Key：
29	```
30	ARK_API_KEY=your-actual-api-key-here
31	```
32
33	### 或使用环境变量
34
35	```bash
36	export ARK_API_KEY="your-api-key"
37	```
38
39	### 加载优先级
40
41	1. 系统环境变量 (`process.env`)
42	2. 当前目录 `.canghe-skills/.env`
43	3. 用户主目录 `~/.canghe-skills/.env`
44
45	## 使用方法
46
47	### 1. 基础视频分析（Files API 方式 - 推荐）
48
49	```bash
50	cd ~/.openclaw/workspace/skills/volcengine-video-understanding
51	python3 scripts/video_understand.py /path/to/video.mp4 "描述这个视频的内容"
52	```
53
54	### 2. 视频问答
55
56	```bash
57	python3 scripts/video_understand.py /path/to/video.mp4 "视频中出现了哪些人物？"
58	```
59
60	### 3. 情感分析
61
62	```bash
63	python3 scripts/video_understand.py /path/to/video.mp4 "分析视频中人物的情感变化"
64	```
65
66	### 4. 指定模型和帧率
67
68	```bash
69	python3 scripts/video_understand.py /path/to/video.mp4 "总结视频要点" \
70	--model doubao-seed-2-0-pro-260215 \
71	--fps 2
72	```
73
74	### 5. 保存结果到文件
75
76	```bash
77	python3 scripts/video_understand.py /path/to/video.mp4 "描述视频" --output result.json
78	```
79
80	## 参数说明
81
82	\| 参数 \| 默认值 \| 说明 \|
83	\|------\|--------\|------\|
84	\| `video_path` \| 必填 \| 视频文件路径 \|
85	\| `instruction` \| 必填 \| 分析指令/问题 \|
86	\| `--model` \| doubao-seed-2-0-pro-260215 \| 模型 ID \|
87	\| `--fps` \| 1 \| 视频采样帧率（预处理） \|
88	\| `--output` \| - \| 结果输出文件路径 \|
89
90	## 支持的模型
91
92	- `doubao-seed-2-0-pro-260215` (默认)
93	- `doubao-seed-2-0-lite-250728`
94	- `doubao-seed-1-6-251015`
95	- 其他 Seed 系列视频理解模型
96
97	## 分析示例
98
99	### 示例 1：视频内容描述
100	```bash
101	python3 scripts/video_understand.py ~/Desktop/video.mp4 "详细描述这个视频的内容，包括场景、人物和动作"
102	```
103
104	### 示例 2：视频摘要
105	```bash
106	python3 scripts/video_understand.py ~/Desktop/video.mp4 "用3句话总结这个视频的要点"
107	```
108
109	### 示例 3：动作识别
110	```bash
111	python3 scripts/video_understand.py ~/Desktop/video.mp4 "视频中的人物在做什么动作？按时间顺序描述"
112	```
113
114	### 示例 4：场景分析
115	```bash
116	python3 scripts/video_understand.py ~/Desktop/video.mp4 "分析视频中的场景变化和环境特征"
117	```
118
119	## 技术细节
120
121	### 调用流程
122
123	1. 上传视频：通过 Files API 上传本地视频文件，指定 FPS 预处理配置
124	2. 等待处理：等待视频预处理完成（状态变为 processed）
125	3. 创建任务：调用 Responses API 进行视频理解
126	4. 获取结果：返回分析结果
127
128	### API 格式
129
130	Files API 上传：
131	```bash
132	curl https://ark.cn-beijing.volces.com/api/v3/files \
133	-H "Authorization: Bearer $ARK_API_KEY" \
134	-F 'purpose=user_data' \
135	-F 'file=@video.mp4' \
136	-F 'preprocess_configs[video][fps]=1'
137	```
138
139	Responses API 分析：
140	```json
141	{
142	"model": "doubao-seed-2-0-pro-260215",
143	"input": [
144	{
145	"role": "user",
146	"content": [
147	{
148	"type": "input_video",
149	"file_id": "file-xxxx"
150	},
151	{
152	"type": "input_text",
153	"text": "用户指令"
154	}
155	]
156	}
157	]
158	}
159	```
160
161	### FPS 设置建议
162
163	\| FPS \| 适用场景 \|
164	\|-----\|----------\|
165	\| 0.3-0.5 \| 慢节奏视频、静态场景、节省token \|
166	\| 1 \| 一般视频分析（默认） \|
167	\| 2-3 \| 快速动作、细节分析 \|
168
169	## 限制
170
171	- 视频格式：MP4（推荐）、MOV、AVI
172	- 文件大小：最大 512MB（Files API 方式）
173	- 存储时间：上传的文件默认存储 7 天
174	- 处理时间：根据视频长度和复杂度，通常 10-60 秒
175
176	## Python API 使用
177
178	```python
179	from scripts.video_understand import analyze_video
180
181	result = analyze_video(
182	file_path="/path/to/video.mp4",
183	instruction="描述视频内容",
184	model="doubao-seed-2-0-pro-260215",
185	fps=1
186	)
187
188	# 提取回答
189	text = ""
190	for item in result.get("output", []):
191	if item.get("type") == "message":
192	for content in item.get("content", []):
193	if content.get("type") == "output_text":
194	text = content.get("text", "")
195	break
196
197	print(text)
198	```
199
200	## 错误处理
201
202	常见错误及解决方案：
203
204	\| 错误 \| 原因 \| 解决方案 \|
205	\|------\|------\|----------\|
206	\| API Key 错误 \| 未设置或错误 \| 检查 ARK_API_KEY 环境变量 \|
207	\| 文件不存在 \| 路径错误 \| 检查文件路径 \|
208	\| 上传失败 \| 文件过大或格式不支持 \| 检查文件大小（<512MB）和格式 \|
209	\| 处理超时 \| 视频过长或复杂 \| 缩短视频或降低 FPS \|
210
211	## 参考文档
212
213	- [火山方舟视频理解文档](https://www.volcengine.com/docs/82379/1895586)
214	- [Files API 文档](https://www.volcengine.com/docs/82379/xxxx)
215	- [Responses API 文档](https://www.volcengine.com/docs/82379/xxxx)

People who liked this also viewed

6 picks

Type

canghe-volcengine-video-understanding

415stars95forks

View on GitHub

How to install canghe-volcengine-video-understanding?

freestylefly/canghe-skills/canghe-volcengine-video-understanding

$npx -y skills add freestylefly/canghe-skills --skill canghe-volcengine-video-understanding

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# 火山视频理解
2
3	使用字节跳动火山方舟视频理解 API（doubao-seed-2-0-pro-260215 等模型）对视频进行深度理解和分析。
4
5	推荐方式：Files API 上传 + Responses API 分析
6	- 支持最大 512MB 视频文件
7	- 自动视频预处理（FPS采样）
8	- 文件可重复使用（存储7天）
9
10	## 功能
11
12	- 视频上传：通过 Files API 上传本地视频（推荐，最大512MB）
13	- 内容理解：分析视频场景、人物、动作、情感
14	- 视频问答：基于视频内容回答用户问题
15	- 视频描述：自动生成视频描述和摘要
16
17	## 前置要求
18
19	需要设置 `ARK_API_KEY` 环境变量。
20
21	### 配置方式（推荐）
22
23	1. 复制配置模板：
24	```bash
25	cp .canghe-skills/.env.example .canghe-skills/.env
26	```
27
28	2. 编辑 `.canghe-skills/.env` 文件，填写你的 API Key：
29	```
30	ARK_API_KEY=your-actual-api-key-here
31	```
32
33	### 或使用环境变量
34
35	```bash
36	export ARK_API_KEY="your-api-key"
37	```
38
39	### 加载优先级
40
41	1. 系统环境变量 (`process.env`)
42	2. 当前目录 `.canghe-skills/.env`
43	3. 用户主目录 `~/.canghe-skills/.env`
44
45	## 使用方法
46
47	### 1. 基础视频分析（Files API 方式 - 推荐）
48
49	```bash
50	cd ~/.openclaw/workspace/skills/volcengine-video-understanding
51	python3 scripts/video_understand.py /path/to/video.mp4 "描述这个视频的内容"
52	```
53
54	### 2. 视频问答
55
56	```bash
57	python3 scripts/video_understand.py /path/to/video.mp4 "视频中出现了哪些人物？"
58	```
59
60	### 3. 情感分析
61
62	```bash
63	python3 scripts/video_understand.py /path/to/video.mp4 "分析视频中人物的情感变化"
64	```
65
66	### 4. 指定模型和帧率
67
68	```bash
69	python3 scripts/video_understand.py /path/to/video.mp4 "总结视频要点" \
70	--model doubao-seed-2-0-pro-260215 \
71	--fps 2
72	```
73
74	### 5. 保存结果到文件
75
76	```bash
77	python3 scripts/video_understand.py /path/to/video.mp4 "描述视频" --output result.json
78	```
79
80	## 参数说明
81
82	\| 参数 \| 默认值 \| 说明 \|
83	\|------\|--------\|------\|
84	\| `video_path` \| 必填 \| 视频文件路径 \|
85	\| `instruction` \| 必填 \| 分析指令/问题 \|
86	\| `--model` \| doubao-seed-2-0-pro-260215 \| 模型 ID \|
87	\| `--fps` \| 1 \| 视频采样帧率（预处理） \|
88	\| `--output` \| - \| 结果输出文件路径 \|
89
90	## 支持的模型
91
92	- `doubao-seed-2-0-pro-260215` (默认)
93	- `doubao-seed-2-0-lite-250728`
94	- `doubao-seed-1-6-251015`
95	- 其他 Seed 系列视频理解模型
96
97	## 分析示例
98
99	### 示例 1：视频内容描述
100	```bash
101	python3 scripts/video_understand.py ~/Desktop/video.mp4 "详细描述这个视频的内容，包括场景、人物和动作"
102	```
103
104	### 示例 2：视频摘要
105	```bash
106	python3 scripts/video_understand.py ~/Desktop/video.mp4 "用3句话总结这个视频的要点"
107	```
108
109	### 示例 3：动作识别
110	```bash
111	python3 scripts/video_understand.py ~/Desktop/video.mp4 "视频中的人物在做什么动作？按时间顺序描述"
112	```
113
114	### 示例 4：场景分析
115	```bash
116	python3 scripts/video_understand.py ~/Desktop/video.mp4 "分析视频中的场景变化和环境特征"
117	```
118
119	## 技术细节
120
121	### 调用流程
122
123	1. 上传视频：通过 Files API 上传本地视频文件，指定 FPS 预处理配置
124	2. 等待处理：等待视频预处理完成（状态变为 processed）
125	3. 创建任务：调用 Responses API 进行视频理解
126	4. 获取结果：返回分析结果
127
128	### API 格式
129
130	Files API 上传：
131	```bash
132	curl https://ark.cn-beijing.volces.com/api/v3/files \
133	-H "Authorization: Bearer $ARK_API_KEY" \
134	-F 'purpose=user_data' \
135	-F 'file=@video.mp4' \
136	-F 'preprocess_configs[video][fps]=1'
137	```
138
139	Responses API 分析：
140	```json
141	{
142	"model": "doubao-seed-2-0-pro-260215",
143	"input": [
144	{
145	"role": "user",
146	"content": [
147	{
148	"type": "input_video",
149	"file_id": "file-xxxx"
150	},
151	{
152	"type": "input_text",
153	"text": "用户指令"
154	}
155	]
156	}
157	]
158	}
159	```
160
161	### FPS 设置建议
162
163	\| FPS \| 适用场景 \|
164	\|-----\|----------\|
165	\| 0.3-0.5 \| 慢节奏视频、静态场景、节省token \|
166	\| 1 \| 一般视频分析（默认） \|
167	\| 2-3 \| 快速动作、细节分析 \|
168
169	## 限制
170
171	- 视频格式：MP4（推荐）、MOV、AVI
172	- 文件大小：最大 512MB（Files API 方式）
173	- 存储时间：上传的文件默认存储 7 天
174	- 处理时间：根据视频长度和复杂度，通常 10-60 秒
175
176	## Python API 使用
177
178	```python
179	from scripts.video_understand import analyze_video
180
181	result = analyze_video(
182	file_path="/path/to/video.mp4",
183	instruction="描述视频内容",
184	model="doubao-seed-2-0-pro-260215",
185	fps=1
186	)
187
188	# 提取回答
189	text = ""
190	for item in result.get("output", []):
191	if item.get("type") == "message":
192	for content in item.get("content", []):
193	if content.get("type") == "output_text":
194	text = content.get("text", "")
195	break
196
197	print(text)
198	```
199
200	## 错误处理
201
202	常见错误及解决方案：
203
204	\| 错误 \| 原因 \| 解决方案 \|
205	\|------\|------\|----------\|
206	\| API Key 错误 \| 未设置或错误 \| 检查 ARK_API_KEY 环境变量 \|
207	\| 文件不存在 \| 路径错误 \| 检查文件路径 \|
208	\| 上传失败 \| 文件过大或格式不支持 \| 检查文件大小（<512MB）和格式 \|
209	\| 处理超时 \| 视频过长或复杂 \| 缩短视频或降低 FPS \|
210
211	## 参考文档
212
213	- [火山方舟视频理解文档](https://www.volcengine.com/docs/82379/1895586)
214	- [Files API 文档](https://www.volcengine.com/docs/82379/xxxx)
215	- [Responses API 文档](https://www.volcengine.com/docs/82379/xxxx)

People who liked this also viewed

6 picks

Type