Byted Mediakit Video

Video Skills

前置说明

开始前必须先读取 ./reference/shared.md 的内容，其中包含前置检查、异步任务机制、结果查询等说明。

工具列表

高光片段提取

能力描述

智能捕捉视频"情绪波峰"与"关键动作"，输出精准时间戳、高光打分、OCR 文本和画面描述等元数据，供下游进行更灵活的二次开发。 支持短剧（Miniseries）和小游戏（Game）两种分析模型。 使用限制：单次最多 100 个视频，累计时长不超过 300 分钟。

执行方式

参数

调用示例

mediakit-cli video analyze-video-highlights \
  --video-urls '["https://example.com/video_url"]' \
  --model Miniseries \
  --mode StorylineCuts \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video analyze-video-highlights
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

剧情故事线分析

能力描述

智能解析影视剧内容，生成结构化剧情线，供智能剪辑、内容检索与互动播放等场景使用。 基于大模型视频理解能力，对输入的单个或多个长视频（如电影、电视剧）进行分析，提取并组织成一份完整的故事线。 该故事线由一系列按时间顺序排列的剧情片段（Clips）和基于片段聚合的高光故事线（Highlights）组成。 使用限制：单次最多 30 个视频，单个视频时长不超过 2.5 小时。

执行方式

参数

调用示例

mediakit-cli video analyze-video-storyline \
  --video-urls '["https://example.com/video_url"]' \
  --enable-snapshot \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video analyze-video-storyline
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

语音转字幕（ASR）

能力描述

对输入视频或音频进行语音识别，输出带时间戳的字幕片段。 支持格式：主流音视频格式（如mp4、mov、mp3、m4a、wav等）。 输入：video_url和audio_url二选一。

执行方式

参数

调用示例

mediakit-cli video asr-subtitles \
  --video-url https://example.com/video_url \
  --content-type speech \
  --language cmn-Hans-CN \
  --enable-speaker-info \
  --enable-confidence \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video asr-subtitles
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

生成式画质增强

能力描述

生成式视频增强修复（generative_video_restoration）是基于扩散大模型（Diffusion-based Large Model）的生成式视频修复技术。不仅可以还原被破坏的像素，更借助大规模预训练积累的丰富视觉先验，主动补全细节、理解语义，生成真实、自然、高保真的视频内容。

执行方式

参数

调用示例

mediakit-cli video enhance-video-generative \
  --video-url https://example.com/video_url \
  --resolution 720p \
  --bitrate-level medium \
  --fps 30 \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video enhance-video-generative
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

画质增强

能力描述

画质增强：针对 AIGC / UGC / 短剧 / 教育 / 游戏 / 老片修复等场景，提供画质提升 + 超分增强一站式解决方案。依托 AI MediaKit 智能媒体处理引擎，融合视频内容理解、画质指标智能决策、多维度增强原子算法，实现画质的全面优化。 支持格式：主流视频格式如mp4、flv、ts、avi、mov、wmv、mkv。 使用限制：单文件大小不超过100G。

执行方式

参数

调用示例

mediakit-cli video enhance-video \
  --video-url https://example.com/video_url \
  --scene common \
  --tool-version standard \
  --resolution 240p \
  --resolution-limit 1 \
  --fps 1.0 \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video enhance-video
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

精细化字幕擦除

能力描述

针对视频中的字幕，实现高质量的无痕擦除，最大程度的还原视频画面。 支持格式：主流视频格式如mp4、flv、ts、avi、mov、wmv、mkv。

执行方式

参数

调用示例

mediakit-cli video erase-video-subtitle-pro \
  --video-url https://example.com/video_url \
  --mode Subtitle \
  --output-encode-mode Quality \
  --erase-ratio-location '[{"top_left_x": 1.0, "top_left_y": 1.0, "bottom_right_x": 1.0, "bottom_right_y": 1.0}]' \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video erase-video-subtitle-pro
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

字幕擦除（标准版）

能力描述

智能检测并擦除视频画面中已有的硬字幕，保留原始背景。 支持格式：主流视频格式如mp4、flv、ts、avi、mov、wmv、mkv。

执行方式

参数

调用示例

mediakit-cli video erase-video-subtitle \
  --video-url https://example.com/video_url \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video erase-video-subtitle
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

高光智剪-短剧

能力描述

深度理解短剧角色、剧情与故事线，自动提取高光片段并混剪成投流视频。 支持故事线混剪模式（StorylineCuts），可选"短剧三要素"视觉模板，输出高光集锦、单集预告等。 支持输出详细分镜信息（storyboard）。 使用限制：单次最多 100 个视频，累计时长不超过 300 分钟。

执行方式

参数

调用示例

mediakit-cli video generate-highlights-microdrama \
  --video-urls '["https://example.com/video_url"]' \
  --mode StorylineCuts \
  --enable-generate-video \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video generate-highlights-microdrama
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

高光智剪-小游戏

能力描述

识别小游戏录屏视频中的核心玩法与高光事件（如连击、通关、极限操作等）， 快速生成用于买量的视频素材。支持提供游戏名称、玩法描述、高光定义以辅助模型更精准识别。 使用限制：本期仅支持单视频输入。

执行方式

参数

调用示例

mediakit-cli video generate-highlights-minigame \
  --video-urls '["https://example.com/video_url"]' \
  --mode HighlightExtract \
  --enable-generate-video \
  --minigame-info '{"game_name": "demo"}' \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video generate-highlights-minigame
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

视频绿幕抠图

能力描述

对以绿幕或纯色为背景的视频进行抠图，自动识别主体（人物、物品、动物等），同时移除背景，生成背景透明的视频。 输出视频格式为 WEBM（默认）或 MOV，分辨率与原片对齐。 支持的格式：主流视频格式如 mp4、flv、ts、avi、mov、mkv、wmv。

执行方式

参数

调用示例

mediakit-cli video matte-greenscreen-video \
  --video-url https://example.com/video_url \
  --format WEBM \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video matte-greenscreen-video
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

视频人像抠图

能力描述

自动识别人物主体，同时移除背景，生成背景透明的视频，适用于背景替换等场景。 输出格式为 WEBM（默认）或 MOV，分辨率与原片对齐。 支持的格式：主流视频格式如 mp4、flv、ts、avi、mov、mkv、wmv。

执行方式

参数

调用示例

mediakit-cli video matte-portrait-video \
  --video-url https://example.com/video_url \
  --format WEBM \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video matte-portrait-video
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

视频元信息获取

能力描述

对输入视频 Url（需公网可访问） 进行探测，输出标准化媒资元信息，覆盖容器层（format_meta）、视频流层（video_stream_meta）与音频流层（audio_stream_meta）。 字段分类参考 ffprobe，并对 VOD 原始返回做精简与统一，便于上层做分辨率/帧率/码率/编码等策略判断。 使用限制：仅支持公网 HTTP/HTTPS URL；输入视频分辨率最高支持 4K。

执行方式

参数

调用示例

mediakit-cli video probe-video-metadata \
  --video-url https://example.com/video_url \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video probe-video-metadata
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

场景切分

能力描述

依据视频转场与画面变化自动切分场景，输出切片时间轴和（可选）切片文件。 支持格式：MP4、FLV、ASF、RM、RMVB、MPEG、MOV、AVI、MPEGTS、M4S、WMV、3GP、TS、MPG、WEBM、MKV、WM、MPE、VOB、DAT、MP4V、M4V、F4V、MXF、QT 等主流视频格式。 使用限制：单个视频时长不超过 2 小时。

执行方式

参数

调用示例

mediakit-cli video segment-scenes \
  --video-url https://example.com/video_url \
  --enable-clip-fade \
  --segment-threshold 10 \
  --min-duration 3 \
  --max-duration 30 \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video segment-scenes
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>

MediaKit 共享规则

本技能指导你如何通过 mediakit-cli 操作媒体资源，以及调用过程中的通用规则和注意事项。

前置检查

依赖安装

首次使用前，确认 CLI 已安装：

# 安装
npm install -g @volcengine/mediakit-cli

# 验证
mediakit-cli --version

鉴权信息检查

优先级：环境变量 > 配置文件（文件路径 ~/.mediakit/config.json）

字段说明

• 环境变量/配置文件：MEDIAKIT_API_KEY、MEDIAKIT_ENDPOINT、MEDIAKIT_SURFACE、MEDIAKIT_RUNTIME

任一必填项缺失时，终止执行并输出所有缺失项的列表及修复建议。

云端调用会自动携带 x-surface / x-runtime。Header 优先级为：环境变量 > ~/.mediakit/config.json > 默认值/环境探测。当本 Skill/Plugin 通过 mediakit-cli 调用云端能力时，运行环境应注入 MEDIAKIT_SURFACE=skill|plugin 与 MEDIAKIT_RUNTIME=<宿主>；CLI 会保留原始产物前缀并上报 x-surface=cli/skill|cli/plugin。若未显式配置，CLI 默认按 x-surface=cli，x-runtime 依次回退 IDENTITY_NAME / OPENCLAW_SERVICE_MARKER 环境探测，最后为 unknown。

来源上报约束

• Skill 调用 mediakit-cli 时，必须显式设置 MEDIAKIT_SURFACE=skill，不能依赖用户已有环境变量。
• Plugin 调用 mediakit-cli 时，必须显式设置 MEDIAKIT_SURFACE=plugin，不能复用 Skill 的取值。
• 宿主环境标识建议同时显式设置 MEDIAKIT_RUNTIME=<宿主>；若未设置，CLI 会回退为环境探测值或 unknown。

MEDIAKIT_SURFACE=skill MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video

MEDIAKIT_SURFACE=plugin MEDIAKIT_RUNTIME=<runtime> mediakit-cli editing add-image-to-video

CLI 使用方式

初始化配置

首次使用建议先运行初始化向导：

mediakit-cli init

Agent 非交互初始化可显式写入请求来源与运行时配置：

mediakit-cli init --mode cloud-first --api-key <key> --runtime <runtime> --surface cli --yes
mediakit-cli init --mode local-first --api-key <key> --endpoint <url> --output-path ~/mediakit-output --runtime <runtime> --surface cli --credential-store config --yes

初始化后常用命令如下：

# 查看当前配置
mediakit-cli config show

# 切换默认模式到本地优先
mediakit-cli config set mode local-first

# 切换默认模式到云端优先
mediakit-cli config set mode cloud-first

# 刷新环境检查并查看依赖状态
mediakit-cli doctor

命令结构

MediaKit CLI 统一使用 domain + tool 的调用方式：

mediakit-cli {domain} {tool} [flags]

常见帮助命令：

# 查看所有 domain
mediakit-cli --domains

# 查看某个分组下的工具列表
mediakit-cli {domain} --help

# 查看具体工具的参数
mediakit-cli {domain} {tool} --help

# 动态发现工具能力与返回结构
mediakit-cli {domain} {tool} --schema
mediakit-cli --local {domain} {tool} --schema

当前产物覆盖的 domain 包括：editing, video。

Schema 发现

每个 capability 命令都支持 --schema，用于 Agent 动态读取工具能力，不要求传必填业务参数。

返回结构包含：

• name：工具名，使用 snake_case，如 add_image_to_video
• description：工具描述，自动包含 Mode 与 Async 信息
• input_schema：输入参数 JSON Schema
• output_schema：当前执行模式下的返回结构

输出区分规则：

• 默认按全局 mode 配置解析返回面
• --local ... --schema 输出本地模式返回面，本地模式直接返回最终结果字段
• 云端异步工具输出 task_id / request_id，并在 final_result 中描述 query-task 完成态结果
• query-task 是 cloud only，schema 描述任务状态与完成态结果

示例：

mediakit-cli editing trim-video --schema
mediakit-cli --local editing trim-video --schema

单次调用模式覆盖

除 config set mode 设置默认模式外，还支持仅对当前命令生效的临时覆盖：

mediakit-cli --local editing add-image-to-video

mediakit-cli --cloud editing add-image-to-video

补充规则：

• --local / --cloud 只影响当前命令，不修改全局 config.mode
• --local 与 --cloud 互斥，不能同时传入

异步任务

提交异步媒体处理任务成功后会返回 task_id 字段。通过 shared query-task 命令查询结果。

mediakit-cli shared query-task --task-id <task_id>

local / cloud 约束

• query-task 是 cloud only 工具
• local 模式下不支持 query-task
• 当前本轮能力以云端执行为主；如需显式声明，请优先使用 --cloud

Cloud 模式媒体输入补充

• 当命令以 --cloud 或 cloud-first 策略执行时，媒体输入参数（如 video_url、audio_url、image_url、subtitle_url、sub_image_url 及对应数组/对象子字段）可传入 http:// / https:// URL、mediakit://... file_id 或本地文件路径
• http:// / https:// URL 与 mediakit://... file_id 会原样提交；本地文件路径会由 CLI 先上传为 mediakit://... file_id，再提交给云端工具
• 各工具 reference 中的参数说明来自 APIHub/OpenAPI 原始字段描述；若其中写有公网 URL 或 HTTP/HTTPS URL，表示云端 API 最终接收的资源形态，不限制 CLI cloud 模式的本地路径预处理能力

Local 模式补充

• 本地输出目录优先级：--output-path > MEDIAKIT_OUTPUT_PATH > config output_path > ~/.mediakit/temp
• 当 --output-path 指向具体媒体文件名时，直接作为最终输出文件；否则按输入文件名生成 {原文件名}_{工具名}.{ext}，重复时追加 6 位随机数
• 无法从输入 URL 或路径提取文件名时，退回 {工具名}-{UnixNano}.{ext}
• local 模式依赖 ffmpeg / ffprobe，缺失时错误中会给出 install_guide
• local 模式媒体处理输出必须贴合接口 response schema，禁止输出内部执行元数据

错误响应

• CLI cloud 模式直接透传 API 返回的原始 error 对象，不提取 message
• CLI local 模式返回结构化错误：{"error":{"type":"...","code":"...","message":"..."}}
• MCP error_response 直接透传原始 error 内容，dict 原样作为 error 字段值

幂等参数维护

补充规则：

• client_token 长度不超过 64 个字符
• callback_args 可用于回调透传与对账追踪

轮询策略

视频识别字幕（OCR）

能力描述

识别视频画面中的字幕/文字内容，输出带时间戳的字幕片段。 支持格式：主流视频格式如 mp4、flv、ts、avi、mov、wmv、mkv。

执行方式

参数

调用示例

mediakit-cli video video-ocr \
  --video-url https://example.com/video_url \
  --mode Subtitle \
  --callback-args sample-callback-args \
  --client-token demo-client-token

输出格式

{
  "task_id": "task_demo_001",
  "request_id": "req_demo_001"
}

任务结果查询

提交成功后会返回 task_id，再执行 mediakit-cli shared query-task --task-id <task_id> 查询。

• 当前命令：mediakit-cli video video-ocr
• 推荐查询：mediakit-cli shared query-task --task-id <task_id>