Volcengine AI MediaKit#

---

前置条件#

• 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：

bash

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_textOCR 文字提取/识别视频中的屏幕文字ocr_text_extract擦除视频硬字幕subtitle_removal给视频添加/嵌入字幕（烧录字幕）add_subtitle视频场景分割/智能切片intelligent_slicing人像抠图/人像分割portrait_matting绿幕抠像/绿屏抠像green_screenAI 漫剧转绘（漫画风/3D卡通风格）comic_style短剧高光剪辑/精彩片段提取highlightAI 视频翻译（字幕/语音/面容翻译）video_translation查询翻译项目状态/重启翻译轮询poll_translation查询翻译项目列表list_translationAI 解说视频生成（短剧解说/二创）drama_recapAI 剧本还原（视频转结构化剧本）drama_script查询媒资信息（Vid 详情+播放地址）get_media_info

3) 构造参数并执行#

视频编辑类

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

媒体处理类

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

AI 内容分析类

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

AI 内容生成类

脚本用途详细参数comic_style.py '<json>'AI 漫剧转绘references/22-comic-style.mdvideo_translation.py '<json>'AI 视频翻译references/24-video-translation.mddrama_recap.py '<json>'AI 解说视频生成references/25-drama-recap.mddrama_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 字段包含可直接复制执行的重启命令。

---

示例#

bash

# 本地文件先上传拿到 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": "说明"}

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

json

{
  "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 资源的计费构成，避免在普通剪辑/处理对话中主动展开计费细节。