Volcengine AI MediaKit

火山引擎 AI MediaKit 音视频处理 Skill。当用户需要对音视频进行加工处理时触发。处理完成后自动查询任务状态并返回产物播放链接。核心能力分为七类：1. 视频处理：多片段拼接、片段裁剪、画面翻转、视频播放调速、音频播放调速、图片合成视频、音画合成、提取音轨、音频混音; 2. 音频处理：人声/伴奏分离、...

Security Scan

The skill's code and SKILL.md largely match a Volcengine/VOD media-processing tool, but there are mismatches between the declared registry metadata and the runtime instructions plus some surprising behaviors (automatic .env loading from multiple locations) that warrant caution before installing.

Purpose & Capability

The SKILL.md and included scripts clearly require Volcengine VOD credentials (VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY) and a VOD space name (VOD_SPACE_NAME), which are appropriate for the described media-processing purpose. However the registry metadata reported 'Required env vars: none' and 'Primary credential: none' — that is inconsistent and misleading. The presence of many VOD-specific API calls and upload logic is coherent with the stated purpose, but the registry metadata mismatch is a red flag.

Instruction Scope

SKILL.md states scripts will auto-load a .env file in the working directory, but ApiManage (in code) attempts to load .env from multiple locations (cwd, script dir, and the user's home directory). Loading ~/.env without prominent warning expands file-read scope beyond what the prose implies and could surface unrelated secrets. Other runtime behaviors (network calls to VOD APIs, uploading media, reading local files) are expected for this skill; upload_media enforces local-file path restrictions to workspace/, userdata/, and /tmp which is a positive control.

Install Mechanism

No install spec or external downloads; the package is delivered as code files (Python scripts). No remote fetching/extracting at install time was observed in provided files, so installation does not execute arbitrary remote installers. However the included scripts are executable Python code and will run network operations when invoked.

Credentials

Requiring VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, and VOD_SPACE_NAME is proportionate to a VOD/MediaKit integration. The concern is twofold: (1) the registry metadata omits these requirements (misleading), and (2) the code's .env loading behavior (includes home directory) can import unrelated environment variables/credentials into the process, increasing the blast radius. The skill does not request unrelated third-party credentials, but it does read environment and .env files.

Persistence & Privilege

The skill is not marked always:true and does not request elevated platform privileges. It does not appear to modify other skills or global agent configuration. Autonomous invocation remains allowed (platform default) but does not combine here with other high-risk flags.

What to consider before installing

Key points before installing or enabling this skill: - Registry vs runtime mismatch: The registry metadata indicates no required environment variables but the SKILL.md and the code require VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY and a VOD space name — the metadata is inaccurate. Treat the .env/credential requirements as real. - Credential handling: Provide a least-privilege Volcengine account/key for this skill (dedicated service account) and avoid using broadly privileged credentials. Rotate or scope the keys if possible. - .env loading behavior: The code will attempt to load a .env from the working directory, the skill directory, or the user's home directory (~/.env). If you keep sensitive secrets in ~/.env, they may be read by this skill. Consider using a dedicated working directory or explicitly setting only the required environment variables (not a global ~/.env). - Local file access: upload_media.py restricts uploads to workspace/, userdata/, and /tmp — that's good. Still only place media you intend to upload in those directories. - Network behavior: The scripts make direct calls to Volcengine VOD APIs and also perform HTTP PUTs to storage endpoints (TOS). Review network policies / proxy logs if you need to audit outbound calls. Inspect the vod_transport module (not included in the excerpt) to confirm exactly which endpoints and auth mechanisms are used. - Run in isolation first: Test the skill in an isolated environment (dedicated VM/container) with test credentials and non-sensitive media to observe behavior and network calls. - Ask the publisher or registry owner to correct the metadata to list required env vars and provide a homepage/source link. If you cannot verify the origin, avoid providing high-privilege credentials. If you want, I can: (1) flag exact lines that load .env and where those locations are searched, (2) search the omitted files (vod_transport) for remote endpoints or suspicious behavior, or (3) suggest a minimal set of IAM permissions for a service account usable with this skill.

---

前置条件

• Python：确认 python --version ≥ 3.6
• 环境变量（必需，也可通过工作目录下的 .env 文件配置，脚本会自动加载）：
  • VOLCENGINE_ACCESS_KEY — 火山引擎 Access Key
  • VOLCENGINE_SECRET_KEY — 火山引擎 Secret Key
  • VOD_SPACE_NAME — VOD 空间名称
• 依赖：脚本依赖 python-dotenv requests urllib

---

参数传入方式

所有脚本支持两种 JSON 参数传入方式：

1. 内联 JSON（适合简单参数）：python script.py '{"key":"value"}'
2. 文件引用（推荐，避免 shell 转义问题）：python script.py @params.json

@ 前缀表示从文件读取 JSON 内容，文件路径相对于当前工作目录。

---

结果交付规则

• 提交异步任务成功后会返回异步任务id，字段为 VCCreativeId 或 TaskId，在给用户交付最终产物时，必须包含异步任务id
• 在展示最终产物链接时，禁止随意修改链接内容
• 优先将产物链接提供给用户

---

注意

当用户询问当前 Skill 有什么能力时，直接返回 references/00-detail.md 的内容，并停止后续流程，等待用户输入。

工作流程

1) 识别输入视频类型（必要时先上传拿 vid://...）

后续所有处理脚本优先使用 VOD 侧资源引用：

• Vid：vid://vxxxx（或部分脚本接受裸 vxxxx 并自动补 vid://）
• DirectUrl / FileName：directurl://<vod_file_name>（媒体类任务用 DirectUrl 时会要求 FileName + SpaceName）

当用户提供的是以下输入之一，需要先执行上传逻辑，拿到 Vid 后再继续：

• 本地文件路径：如 /path/to/a.mp4
• http/https 链接：如 https://example.com/a.mp4（会走 URL 拉取上传，并轮询上传结果）

统一用 scripts/upload_media.py：

python <SKILL_DIR>/scripts/upload_media.py "<local_file_path_or_http_url>" [space_name]

脚本输出中 Source 字段即 vid://...，可直接作为后续处理输入。

安全限制：本地文件上传仅允许 workspace/、userdata/ 和 /tmp 目录下的文件。

2) 识别用户意图 → 选择对应处理脚本

根据用户需求，按以下决策树选择脚本：

用户意图	脚本
多个视频/音频合成一个（顺序拼接）	stitching
截取视频/音频的某个时间片段	clipping
加速/慢放/变速	speedup
镜像/上下翻转/左右翻转	flip
多张图片串联生成视频	image_to_video
替换/叠加视频的背景音乐	compile
只要视频里的音频轨	extract_audio
多条音频同时叠加播放（混音）	mix_audios
分离人声和伴奏/背景音	voice_separation
去除环境噪音/电流杂音/风噪	noise_reduction
模糊/低画质视频修复（压缩伪影/噪点/划痕）	quality_enhance
低分辨率视频提升（如 720P→1080P）	super_resolution
低帧率视频插帧提升流畅度（如 30fps→60fps）	interlacing
语音识别/ASR/提取视频中的文字对白	asr_speech_to_text
OCR 文字提取/识别视频中的屏幕文字	ocr_text_extract
擦除视频硬字幕	subtitle_removal
给视频添加/嵌入字幕（烧录字幕）	add_subtitle
视频场景分割/智能切片	intelligent_slicing
人像抠图/人像分割	portrait_matting
绿幕抠像/绿屏抠像	green_screen
AI 漫剧转绘（漫画风/3D卡通风格）	comic_style
短剧高光剪辑/精彩片段提取	highlight
AI 视频翻译（字幕/语音/面容翻译）	video_translation
查询翻译项目状态/重启翻译轮询	poll_translation
查询翻译项目列表	list_translation
AI 解说视频生成（短剧解说/二创）	drama_recap
AI 剧本还原（视频转结构化剧本）	drama_script
查询媒资信息（Vid 详情+播放地址）	get_media_info

3) 构造参数并执行

视频编辑类

脚本	用途	详细参数
stitching.py '<json>'	视频/音频拼接	references/01-stitching.md
clipping.py '<json>'	视频/音频裁剪	references/02-clipping.md
flip.py '<json>'	视频翻转	references/03-flip.md
speedup.py video '<json>'	视频变速	references/04-speedup.md
speedup.py audio '<json>'	音频变速	references/04-speedup.md
image_to_video.py '<json>'	图片转视频	references/05-image-to-video.md
compile.py '<json>'	音视频合成	references/06-compile.md
extract_audio.py '<json>'	提取音轨	references/07-extract-audio.md
mix_audios.py '<json>'	混音	references/08-mix-audios.md

媒体处理类

脚本	用途	详细参数
voice_separation.py '<json>'	人声分离	references/10-voice-separation.md
noise_reduction.py '<json>'	音频降噪	references/11-noise-reduction.md
quality_enhance.py '<json>'	综合画质修复	references/12-quality-enhance.md
super_resolution.py '<json>'	AI 超分辨率	references/13-super-resolution.md
interlacing.py '<json>'	智能补帧	references/14-interlacing.md

AI 内容分析类

脚本	用途	详细参数
asr_speech_to_text.py '<json>'	语音识别 ASR	references/15-asr-speech-to-text.md
ocr_text_extract.py '<json>'	OCR 文字提取	references/16-ocr-text-extract.md
subtitle_removal.py '<json>'	硬字幕擦除	references/17-subtitle-removal.md
add_subtitle.py '<json>'	添加嵌入字幕	references/18-add-subtitle.md
intelligent_slicing.py '<json>'	智能场景分割	references/19-intelligent-slicing.md
portrait_matting.py '<json>'	人像抠图	references/20-portrait-matting.md
green_screen.py '<json>'	绿幕抠像	references/21-green-screen.md
highlight.py '<json>'	短剧高光剪辑	references/23-highlight.md
get_media_info.py '<json>'	媒资信息查询	references/27-get-media-info.md

AI 内容生成类

脚本	用途	详细参数
comic_style.py '<json>'	AI 漫剧转绘	references/22-comic-style.md
video_translation.py '<json>'	AI 视频翻译	references/24-video-translation.md
drama_recap.py '<json>'	AI 解说视频生成	references/25-drama-recap.md
drama_script.py '<json>'	AI 剧本还原	references/26-drama-script.md

重启轮询

脚本	用途
poll_vcreative.py <task_id>	重启编辑类任务轮询
poll_media.py <task_type> <RunId>	重启媒体处理类任务轮询
poll_translation.py <ProjectId>	重启翻译任务轮询

超时响应中的 resume_hint.command 字段包含可直接复制执行的重启命令。

---

示例

# 本地文件先上传拿到 vid（后续脚本统一用 vid://... 作为输入）
python <SKILL_DIR>/scripts/upload_media.py "/path/to/local.mp4" my_space

# 拼接两个视频，加转场
python <SKILL_DIR>/scripts/stitching.py \
  '{"type":"video","videos":["vid://v0001","vid://v0002"],"transitions":["1182359"]}'

# 使用 @file.json 传参（推荐，避免转义问题）
python <SKILL_DIR>/scripts/stitching.py @params.json

# 人声分离（注意 type 首字母大写）
python <SKILL_DIR>/scripts/voice_separation.py '{"type":"Vid","video":"v0310abc"}'

# 超分到 1080P
python <SKILL_DIR>/scripts/super_resolution.py '{"type":"Vid","video":"v0310xyz","Res":"1080p"}'

# ASR 语音识别
python <SKILL_DIR>/scripts/asr_speech_to_text.py '{"type":"Vid","video":"v0310abc"}'

# 短剧高光剪辑
python <SKILL_DIR>/scripts/highlight.py '{"Vids":["v023xxx","v024xxx"]}'

# AI 视频翻译（中文→英文）
python <SKILL_DIR>/scripts/video_translation.py '{"Vid":"v0d225gxxx","SourceLanguage":"zh","TargetLanguage":"en"}'

# AI 漫剧转绘（漫画风 720p）
python <SKILL_DIR>/scripts/comic_style.py '{"Vid":"v0d012xxxx","Style":"漫画风","Resolution":"720p"}'

# AI 解说视频（自动生成解说词）
python <SKILL_DIR>/scripts/drama_recap.py '{"Vids":["v023xxx"],"AutoGenerateRecapText":true}'

# AI 剧本还原
python <SKILL_DIR>/scripts/drama_script.py '{"Vids":["v023xxx","v024xxx"]}'

# 查询媒资信息
python <SKILL_DIR>/scripts/get_media_info.py '{"vids":"v001,v002"}'

# 超时后重启编辑类轮询
python <SKILL_DIR>/scripts/poll_vcreative.py <异步智剪任务ID> my_space

# 超时后重启媒体类轮询
python <SKILL_DIR>/scripts/poll_media.py videSuperResolution run_yyy my_space

# 超时后重启翻译轮询
python <SKILL_DIR>/scripts/poll_translation.py <ProjectId> my_space

---

错误输出

所有错误统一格式：{"error": "说明"}

超时输出（含重启指令）：

{
  "error": "轮询超时（360 次 × 5s），任务仍在处理中",
  "resume_hint": {
    "description": "任务尚未完成，可用以下命令重启轮询",
    "command": "python <SKILL_DIR>/scripts/poll_media.py videSuperResolution run_yyy my_space"
  }
}

约束

• 调用脚本前必须查看脚本详细参数说明

---

计费说明

仅当用户主动咨询费用或计费规则时，再参考 references/00-billing-instructions.md 中的计费说明，向用户简要说明 volcengine-ai-mediakit 所依赖的 VOD 资源的计费构成，避免在普通剪辑/处理对话中主动展开计费细节。