前置条件
- 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 参数传入方式：
- 内联 JSON（适合简单参数）：
python script.py '{"key":"value"}'
- 文件引用（推荐，避免 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://（媒体类任务用 DirectUrl 时会要求 FileName + SpaceName）
当用户提供的是以下输入之一，需要先执行上传逻辑，拿到 Vid 后再继续：
- 本地文件路径：如
/path/to/a.mp4
http/https 链接：如 https://example.com/a.mp4（会走 URL 拉取上传，并轮询上传结果）
统一用 scripts/upload_media.py：
python /scripts/upload_media.py "" [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) 构造参数并执行
视频编辑类
媒体处理类
AI 内容分析类
AI 内容生成类
重启轮询
| 脚本 | 用途 |
|---|
poll_vcreative.py | 重启编辑类任务轮询 |
poll_media.py | 重启媒体处理类任务轮询 |
poll_translation.py | 重启翻译任务轮询 |
超时响应中的
resume_hint.command 字段包含可直接复制执行的重启命令。
示例
# 本地文件先上传拿到 vid（后续脚本统一用 vid://... 作为输入）
python /scripts/upload_media.py "/path/to/local.mp4" my_space# 拼接两个视频，加转场
python /scripts/stitching.py \
'{"type":"video","videos":["vid://v0001","vid://v0002"],"transitions":["1182359"]}'
# 使用 @file.json 传参（推荐，避免转义问题）
python /scripts/stitching.py @params.json
# 人声分离（注意 type 首字母大写）
python /scripts/voice_separation.py '{"type":"Vid","video":"v0310abc"}'
# 超分到 1080P
python /scripts/super_resolution.py '{"type":"Vid","video":"v0310xyz","Res":"1080p"}'
# ASR 语音识别
python /scripts/asr_speech_to_text.py '{"type":"Vid","video":"v0310abc"}'
# 短剧高光剪辑
python /scripts/highlight.py '{"Vids":["v023xxx","v024xxx"]}'
# AI 视频翻译（中文→英文）
python /scripts/video_translation.py '{"Vid":"v0d225gxxx","SourceLanguage":"zh","TargetLanguage":"en"}'
# AI 漫剧转绘（漫画风 720p）
python /scripts/comic_style.py '{"Vid":"v0d012xxxx","Style":"漫画风","Resolution":"720p"}'
# AI 解说视频（自动生成解说词）
python /scripts/drama_recap.py '{"Vids":["v023xxx"],"AutoGenerateRecapText":true}'
# AI 剧本还原
python /scripts/drama_script.py '{"Vids":["v023xxx","v024xxx"]}'
# 查询媒资信息
python /scripts/get_media_info.py '{"vids":"v001,v002"}'
# 超时后重启编辑类轮询
python /scripts/poll_vcreative.py <异步智剪任务ID> my_space
# 超时后重启媒体类轮询
python /scripts/poll_media.py videSuperResolution run_yyy my_space
# 超时后重启翻译轮询
python /scripts/poll_translation.py my_space
错误输出
所有错误统一格式：{"error": "说明"}
超时输出（含重启指令）：
{
"error": "轮询超时（360 次 × 5s），任务仍在处理中",
"resume_hint": {
"description": "任务尚未完成，可用以下命令重启轮询",
"command": "python /scripts/poll_media.py videSuperResolution run_yyy my_space"
}
}
约束
计费说明
仅当用户主动咨询费用或计费规则时，再参考 references/00-billing-instructions.md 中的计费说明，向用户简要说明 volcengine-ai-mediakit 所依赖的 VOD 资源的计费构成，避免在普通剪辑/处理对话中主动展开计费细节。
by