1仕組みと動作原理
ローカル動画を ByteDance 火山方舟のビデオ理解 API に送信し、Seed シリーズモデルを使用して高度な理解と分析を行います。
skills/canghe-volcengine-video-understanding/SKILL.md
使用字节跳动火山方舟视频理解 API（doubao-seed-2-0-pro-260215 等模型）对视频进行深度理解和分析。
ここで行われていること：コア機能が「動画→外部マルチモーダルモデル」の呼び出しであり、ローカルではオーケストレーションと結果解析のみを行うことを宣言しています。
推奨フローは 2 つのステップです：Files API アップロード + Responses API 分析。
skills/canghe-volcengine-video-understanding/SKILL.md
**推荐方式**：Files API 上传 + Responses API 分析
ここで行われていること：まず動画をファイルとしてアップロードし（大容量ファイル対応、再利用可能）、次に file_id を使用して理解タスクを開始します。
アップロードは multipart 形式で行われ、前処理 FPS 設定が付加されます。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
"preprocess_configs[video][fps]": str(fps)
ここで行われていること：サンプリングフレームレートに従ってサーバー側で動画を事前処理させ、トークンコストとディテールの保持のバランスを取ります。
アップロード後、ファイルステータスをポーリングし、active/processed になるまで待機してから処理を続行します。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
if status in ["active", "processed"]:
ここで行われていること：動画の前処理完了を待機し、準備が整っていない状態での分析開始を防ぎます。
理解タスクには Responses API を使用し、input_video(file_id) と input_text(指示) を一緒に送信します。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
"type": "input_video",
ここで行われていること：動画の参照とユーザーのプロンプトを 1 つのマルチモーダルリクエストとして組み立てます。
認証は環境変数 ARK_API_KEY に依存します（システム環境変数→カレントディレクトリの .env→ユーザーホームディレクトリの .env）。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
return require_env_key("ARK_API_KEY")
ここで行われていること：ホストの common/env_utils から API キーを読み取り、Bearer ヘッダーを付与して火山方舟のエンドポイントを呼び出します。
結果はテキストとして解析でき、--output により JSON としてディスクに保存できます。
skills/canghe-volcengine-video-understanding/scripts/video_understand.py
with open(args.output, 'w', encoding='utf-8') as f:
ここで行われていること：API の生レスポンスを保存するか output_text を抽出して、後処理を容易にします。
デフォルトモデルとサンプリングフレームレートは調整可能です（デフォルト: doubao-seed-2-0-pro-260215 / fps=1）。
skills/canghe-volcengine-video-understanding/SKILL.md
| `--fps` | 1 | 视频采样帧率（预处理） |
ここで行われていること：テンポの遅い動画では FPS を下げてトークンを節約し、動きの速いシーンでは FPS を上げて詳細を維持できます。
2コア機能
01動画コンテンツの理解（シーン/人物/アクション/感情）
02動画コンテンツに基づく Q&A
03動画の説明文および要約の自動生成
04Files API による大容量ファイル（最大 512MB）のアップロード
05モデルおよびサンプリングフレームレートの指定
06前処理完了を待機するポーリング
07結果の JSON ディスク保存 / Python API（analyze_video）の提供
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| api | 火山方舟视频理解 API（Files / Responses），模型 doubao-seed-2-0-pro-260215 等 |
| package | requests（HTTP 客户端） |
| cli | python3（运行 video_understand.py） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: python3 scripts/video_understand.py <video> "<指令>" [--model ...] [--fps N]
- 网络端点: 外部ネットワークアクセスの宣言: POST https://ark.cn-beijing.volces.com/api/v3/files（multipart 動画アップロード、prepro 付き
- 本地工作目录: ファイルの読み書きと成果物の出力: --output で指定された JSON 結果ファイル（with open(args.output, 'w', encoding='utf-8')）
監査ノート： 2 つの独立した理由：①【環境変数の認証情報の読み取り】スクリプト get_api_key() → require_env_key("ARK_API_KEY") が ARK_API_KEY を読み取り、Bearer ヘッダーで火山方舟のエンドポイントに送信します。②【ユーザー素材の外部サービスバックエンド送信】動画が Files API 経由でアップロードされ、Responses API で分析されることで、ローカル動画と分析指示がサードパーティのマルチモーダルモデルに送信され、アカウントのクォータを消費します。判定基準『認証情報/環境変数の読み取り、またはユーザー素材の外部生成/サービスバックエンドへの送信』＝オレンジに該当します。レッドへの引き上げはなし：リバースエンジニアリングなし、なりすましなし、保護のバイパスなし、セキュリティのダウングレードなし（TLS 検証やサンドボックスの無効化は見られない）、任意のコード実行面なし。スクリプトの構造は明確で難読化されておらず、ハードコードされたキーもありません。
5二重目の独立検証
- [ok] 读取 ARK_API_KEY 并外发 — 脚本 get_api_key() 用 require_env_key("ARK_API_KEY")；三处请求均带 "Authorization": f"Bearer {api_key}"。
- [ok] 端点定位 — BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"；风险扫描『URL/端點』与『網路請求』命中 files/responses 与脚本 requests.post/get。
- [ok] 素材上传到外部服务 — upload_video_file() 以 requests.post 到 {BASE_URL}/files 上传视频；analyze_video() 以 file_id 调 /responses。
- [ok] 无本地危险执行面 — 风险扫描『危險旗標/防護繞過』『沙箱/未受控執行』均无命中；脚本无 eval/exec、无 shell。
- [ok] 唯一写盘为 --output — 风险扫描『寫盤/產生檔案』仅命中 open(args.output, 'w', encoding='utf-8')。
- [ok] env_utils 为跨目录依赖 — 脚本 sys.path 插入 COMMON_DIR = Path(__file__).parent.parent.parent / "common"，导入 load_env/require_env_key；该模块位于 skill 目录之外，本报告仅作推测定位。
- [ok] 档位复核 — 读 env 密钥 + 用户视频出网至生成型服务 → orange；无 red 触发项。
- [ok] 元数据与 commit — commit=dd0bf355955b4c82b764740b4183c86a72ba0e0c，license=MIT（仓库根），installs=null。
6結論
最適な用途： 火山方舟（Ark）アカウントをすでに所有しており、ローカル動画のコンテンツ理解/Q&A/要約を必要とする開発者やコンテンツチーム、特に大容量の動画ファイル（≤512MB）を処理するシナリオに適しています。
不向きな用途： 動画やメディア資産の外部ネットワーク送信が禁止されている環境、または厳密なデータコンプライアンス要件がある環境には適していません。ARK_API_KEY やクォータを所有していないユーザー、オフラインでのローカル推論を希望するユーザーには適していません。
Install Agent-Ready
① Verified Mirror 2026-10-10
Option A · Direct DownloadDownload volcengine-video-understanding.tar.gz
sha256:
Option B · Copy Guide for Agent5f1ee27839a37239…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit dd0bf35595.