AI MediaKit
AI MediaKit
文档指南
请输入
- 文档首页
AI MediaKit智能体资源AI MediaKit CLI 用户指南
复制全文
下载 pdfAI MediaKit CLI 用户指南
文档反馈
问问助手AI MediaKit CLI (mediakit-cli) 是 AI MediaKit 的官方命令行工具，将视频剪辑、音频处理、画质增强、字幕擦除等核心能力封装为一组统一、标准、极简的终端命令。不仅如此，mediakit-cli 还支持导出符合 JSON Schema 规范的能力声明，能够与各类 AI 智能体（Agent）无缝集成，在显著降低 Token 消耗的同时，通过自然语言任务描述自动编排并完成复杂的音视频处理。本文为您详细介绍 mediakit-cli 的安装、配置与核心使用方法。
Replay
00:00
/
00:00
Live
Play
00:00
Fullscreen
Cssfullscreen
Click and hold to drag
快速开始：从云端增强到本地剪辑
本节以具体的云端画质超分和本地视频剪辑功能为例，引导您在几分钟内完成从安装、配置 mediakit-cli 到成功产出第一个处理视频的全过程。
准备工作
在开始之前，请确保您已完成以下工作：
- 获取 API Key：访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 AI MediaKit API Key。
- 待处理视频文件 URL：准备一个您希望增强画质的视频文件 URL。请确保该视频 URL 处于公网可访问状态（支持 HTTP/HTTPS 协议），文件大小不超过 10 GB。
- 若您没有可用视频，可参考火山方舟视频生成文档完成视频生成并获取视频地址。
- 为方便您快速测试，本文后续步骤的示例代码中提供了一个可直接使用的演示视频 URL。
步骤 1：安装 CLI
打开终端，执行以下命令（要求您的系统已配置 Node.js v18.0.0 或更高版本）：
步骤 2：初始化 CLI
执行 init 命令配置您的 API Key。
该命令会将您的 API Key 安全地保存在本地配置文件中，为后续所有云端调用提供身份凭证。
步骤 3：提交画质增强任务（云端模式）
使用 video enhance-video 命令提交画质增强任务，并指定输出分辨率为 1080p。
假设您想为本地的视频文件 local_intro.mp4 进行画质增强，则可直接将本地文件路径传给云端任务：
提交成功后，您会看到类似下方的响应。这表示云端已接收您的请求，并开始异步处理。
请复制返回的 task_id，下一步将用它来查询结果。
步骤 4：查询并获取画质增强任务结果
由于画质增强是异步任务，需要一些时间来处理。使用 shared query-task 命令检查任务状态。通过添加 --poll-complete 参数，CLI 会自动轮询，直到任务完成才返回最终结果。
任务处理完成后，终端将打印出包含完整结果的 JSON。
video_url 字段的值就是您增强后的视频文件地址。
步骤 5：在本地裁剪视频（端云协同）
对于裁剪、拼接等轻量编辑任务，使用本地模式（--local）在本地计算机执行，不仅可以免去云端算力计费，还能避免不必要的上传下载带宽开销。
使用步骤 4 获取到的 video_url，并添加 --local flag 调用 trim-video 命令，即可在本地利用本机 FFmpeg 进行快速裁剪：
本地任务是同步执行的，会直接返回结果，无需轮询 task_id：
说明
- 云端模式 (--cloud)：适用于处理复杂、需要弹性算力的 AI 任务（如画质增强、字幕擦除、视频理解）。您既可以提供公网 URL，也可以直接提供本地文件路径，CLI 会自动处理上传，实现无缝体验。任务异步执行，返回 task_id，您需要轮询获取结果。
- 本地模式 (--local)：适用于执行轻量、确定性的编辑任务（如裁剪、拼接、提取音频）。任务同步执行，直接返回结果，零云端成本（依赖本机 FFmpeg）。
- 统一体验：使用同一个 CLI 和同一套命令，通过 --cloud / --local 标志灵活切换，兼顾云端能力与本地效率。
通过上述快速入门，您已经体验了 “云端异步 AI 增强 + 本地同步轻量裁剪” 的端云协同工作流。
接下来，我们将为您系统性地拆解 mediakit-cli 在不同环境下的安装方法、全局配置策略、核心设计规范以及完整的命令参考，帮助您在实际工程或智能体（Agent）编排中更稳定地使用此工具。
安装与部署
环境要求
在安装和使用 mediakit-cli 前，请确保您的系统满足以下要求：
- 操作系统：支持 macOS、Linux 及 Windows。
- CPU 架构：支持 x86_64 (amd64) 和 arm64 架构。
- API Key：您需要访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 AI MediaKit API Key。这是使用所有云端能力的必要前提。
- Node.js（可选）：版本需为 18.0.0 或更高。此项仅在您选择使用 npm 安装方式时为必需。
- 本地依赖（可选）：仅当您计划在本地执行处理任务（即使用 local-first 或 --local 模式）时，才需要安装以下软件：
- FFmpeg ≥ 5.1
- FFprobe ≥ 5.1（通常随 FFmpeg 一起安装）
安装方式
您可根据习惯选择以下三种安装方式之一：
方式 1：npm（推荐，跨平台）
此方法会自动下载并安装与您当前平台和架构匹配的二进制文件。
方式 2：通过一键脚本安装（macOS / Linux）
此脚本会自动识别您的系统架构并将二进制文件下载至 /usr/local/bin。
您可以通过环境变量自定义安装过程：
- INSTALL_DIR：自定义安装目录（默认为 /usr/local/bin，可能需要 sudo 权限）。
- VERSION：安装特定版本（如 v0.1.0）；不指定则安装最新版。
方式 3：npx 免安装单次执行
如果您不希望在全局安装任何包，可以使用 npx 临时运行：
验证安装
执行以下命令，如果能看到版本号和构建时间，说明安装成功。
若终端正确打印出版本号和构建日期，即表示安装成功。
卸载
根据您的安装方式选择对应的卸载命令。
注意
Windows 系统已知限制：
- 一键安装 Shell 脚本不支持 Windows，请使用 npm 方式。
- init --credential-store shell 凭证存储模式在 Windows 上不可用，建议使用 config 或 export 模式。
成功在本地部署客户端后，下一步需要对其进行全局初始化配置，并验证您的本地音视频解码依赖（FFmpeg）是否能够正常工作。
配置与健康检查
初始化配置 (init)
init 命令用于完成全局初始化。您可以指定默认运行模式（优先走云端还是本地），以及凭证（即 AI MediaKit API Key）在本地的存储安全级别。该命令支持交互式（手动问答）与非交互式（自动化脚本）两种模式。
模式 A：非交互式（推荐用于 CI/CD 或 Agent 环境）
通过添加 flag，可以一次性完成所有配置，无需人工干预。
您也可以将 API Key 设置为环境变量 MEDIAKIT_API_KEY，这样在执行 init 命令时就无需再通过 --api-key flag 传入。
初始化参数说明：
模式 B：交互式
如果您在终端中直接运行 mediakit-cli init，CLI 将会通过问答的形式引导您完成配置。对于不需要自定义的选项，直接按回车键跳过即可。
验证配置 (config show)
您可以通过 config show 命令随时查看当前生效的配置项及其来源。
系统会以 (env)、(config)、(default) 等标签清晰地标注每个参数是从环境变量、配置文件还是系统缺省值中加载的，方便调试，如下所示：
健康检查 (doctor)
在本地运行任务前，建议使用 doctor 命令对环境进行一次全面体检。
doctor 命令会自动化检测：
- 服务就绪度：云端连接（cloud_ready）与本地环境（local_ready）的状态。
- 本地依赖：FFmpeg、FFprobe 的版本及音视频编解码器的可用性。如果缺少依赖，体检报告中会给出适合您当前操作系统的安装建议。
说明
核心使用方法
统一命令结构
mediakit-cli 的命令都遵循以下统一的语法结构：
- <domain>：能力域（如 editing 代表剪辑、video 代表视频处理）。
- <tool>：具体原子工具名（如 trim-video 代表视频裁剪）。
调用约定与优先级
全局 Flags
这些 flag 对所有命令都有效。
flag | 类型 | 说明 |
--local | 布尔 | 强制本次调用使用本地模式。 |
--cloud | 布尔 | 强制本次调用使用云端模式。 |
--help, -h | 布尔 | 显示帮助信息。 |
--version, -v | 布尔 | 显示版本信息。 |
--local 和 --cloud 是互斥的，不能同时使用。
能力级 Flags
每个具体的能力（<tool>）都支持这些通用的 flag。
flag | 类型 | 说明 |
--schema | 布尔 | 输出该能力的 JSON Schema，用于 Agent 发现和集成。 |
--output-path | 字符串 | 为本次调用指定输出路径，会覆盖全局配置。 |
--help, -h | 布尔 | 显示该具体能力的参数列表和示例。 |
输出路径优先级
输出文件的存放位置由以下规则决定，优先级从高到低：
- 命令行的 --output-path <path> flag。
- MEDIAKIT_OUTPUT_PATH 环境变量。
- 通过 config set output-path <path> 设置的全局配置。
- 默认路径 ~/.mediakit/temp。
执行模式与降级
- 优先级：单次命令的 --local/--cloud flag > 全局配置的 mode > 默认值 (cloud-first)。
- 静默降级：当模式为 cloud-first 但 API Key 未配置时，CLI 会静默降级到 local-first 模式，并在标准错误流中打印一条警告。
- Agent 调用建议：为了避免意外的静默降级，建议在 Agent 或自动化脚本中显式地使用 --cloud flag，这样在未配置 Key 时会立即报错，而不是执行非预期的本地任务。
注意
退出码已知限制：当前版本中，部分客户端错误（如传入互斥 flag）的退出码（exit code）可能仍然是 0。请在脚本中同时检查响应的 JSON 体是否包含 error 字段，而不是单独依赖退出码来判断成功或失败。
智能能力发现
Agent 发现：--schema
为了向 AI 智能体提供最精准的上下文，mediakit-cli 支持输出标准的 JSON Schema。
该命令输出的定义可以直接被大模型的 Tool Use（工具调用）或 Function Calling 框架消费，无需任何人工二次转换。
用户发现：--help-full
如果您需要手动探索和了解工具有哪些参数，可使用以下指令：
异步任务管理
由于云端能力（video 域和部分 editing 域）属于重消耗任务，系统采用异步模式。调用接口后会立即返回 task_id，您需要通过 shared query-task 追踪结果。
query-task 命令参数：
掌握了上述核心使用方法后，您可以了解当前 v0.1.0-dev 版本支持的完整命令速查手册，方便您在实际开发中查阅。
常用命令参考
说明
随着版本迭代，参数可能发生变化。建议在实际使用中，通过 mediakit-cli <command> --help 获取最准确的信息。
支持命令概览
视频剪辑域（editing）
此域包含 23 个音视频编辑能力。除特别说明外，其余工具均支持云端（异步）和本地（同步）双模式。
editing add-image-to-video — 视频加图片（本地 + 云端）
支持将指定图片（如 Logo、水印等）叠加到视频画面上。
editing add-subtitle-to-video — 视频加字幕（本地 + 云端）
将字幕文件或文本内容按自定义样式压制到视频画面中，生成带内嵌字幕的新视频。
editing adjust-audio-speed — 音频调速（本地 + 云端）
用于音频调速，可调整音频播放倍速，实现快放或慢放效果。
editing adjust-video-speed — 视频调速（本地 + 云端）
用于视频调速，通过调整播放倍速产生快放或慢放效果。
editing adjust-video-volume — 调整视频音量（本地 + 云端）
用于调整输入视频的音量大小，也可实现静音。
editing add-camera-movement-to-video — 视频添加运镜（云端）
对输入视频在指定时间段内添加一种运镜特效，常用于素材二次创作、营销片头、短剧动效等场景。
editing add-filter-to-video — 视频添加滤镜（云端）
为指定视频添加滤镜效果。
editing concat-audio — 音频拼接（本地 + 云端）
拼接多个音频片段。
editing concat-video — 视频拼接（本地 + 云端）
将多个视频按顺序拼接成一个完整的视频文件，并支持在拼接处添加转场效果。
editing crop-video-frame — 视频画面裁剪（云端）
按指定的矩形区域裁剪视频画面，裁剪结果仅保留指定的需要区域。
editing create-gif-from-video — 视频截取动图（云端）
从视频中按指定开始时间和结束时间截取一段画面，生成 GIF 或 WebP 动图，常用于制作封面动图、营销素材和短预览。
editing extract-audio — 提取音频（本地 + 云端）
从输入视频文件中分离音轨，生成独立的音频文件。
editing fade-audio — 音频声音淡入淡出（本地 + 云端）
对输入音频的起止位置实现淡入或淡出效果，输出处理后的音频文件。
editing fade-video-audio — 视频声音淡入淡出（本地 + 云端）
在片头或片尾对输入视频音轨执行淡入或淡出处理，用于弱化音轨突兀的起止，提升成片听感。
editing flip-video — 视频画面翻转（本地 + 云端）
用于视频画面翻转，对指定视频进行上下或左右镜像翻转。
editing image-to-video — 图片转视频（云端）
将多张图片按顺序组合成动态视频，可配置转场动画和镜头内动画。
editing mix-audio — 音频混合（本地 + 云端）
将多个音频文件（如背景音乐、音效、人声）进行混音，生成一个新的音频文件。
editing mux-audio-video — 视频加音频（本地 + 云端）
可将输入的音频流与视频流合并成一个新的视频文件，并可选择保留或替换视频的原有音轨。
editing rotate-video-frame — 视频画面旋转（云端）
用于视频画面旋转，对指定视频进行整体旋转。
editing stitch-video-frames — 视频画面拼接（云端）
将多个视频在空间上按水平或垂直方向拼接成一个完整画面，适用于多视角对比、画面组合等场景。
editing text-to-scrolling-video — 文字生成滚屏视频（云端）
将指定文本内容转换为文字滚屏视频，输出视频为固定 9:16 竖版，常用于小说推文、内容讲解和歌词视频等场景。
editing trim-audio — 音频裁剪（本地 + 云端）
用于音频裁剪，按指定的开始时间和结束时间从输入音频中截取片段。
editing trim-video — 视频裁剪（本地 + 云端）
用于视频裁剪，可按指定的开始和结束时间从输入视频截取片段。
视频处理域（video）
此域包含 30 个 AI 视频处理能力。除特别说明外，其余工具均仅支持云端（异步）模式。
video add-blind-watermark — 添加视频暗水印（云端）
在不影响视频画面视觉质量与完整性的前提下，将一串数字信息隐藏式地嵌入视频文件中。
video extract-highlights — 高光片段提取（云端）
支持短剧和游戏两种模型，提取高光片段的时间戳、打分、OCR 文本和画面描述。
video analyze-storyline — 剧情故事线分析（云端）
基于大模型视频理解分析单个或多个长视频并生成结构化剧情数据，包含剧情片段和高光故事线。
video speech-to-subtitle — 语音转字幕 (ASR)（云端）
从视频或音频的语音中识别并提取带时间戳的字幕文本。
video detect-video-quality-vqscore — 视频画质检测 (VQScore)（云端）
用于视频画质检测。
video generate-commentary-video — 解说视频生成（云端）
基于剧本还原任务，使用自定义或 AI 生成的解说词，生成带 AI 配音与字幕的营销或解说视频。
video generate-commentary-video-for-miniseries — 解说视频生成 (短剧行业模型)（云端）
基于短剧剧集的理解，自动提取高光片段并生成全新解说视频。
video restore-script — 剧本还原（云端）
基于大模型视频理解能力，将短剧视频转化为结构化剧本文本。
video enhance-video-quality — 画质增强（云端）
提供 standard 和 professional 两种版本，利用 AI 算法对视频进行去噪、色彩增强、清晰度提升、瑕疵修复和超分等优化。
video enhance-video-quality-ultra-fast — 视频画质增强极速版（云端）
集成轻量级超分与智能画质增强，采用速度优先策略，高效兼顾处理效率与画面效果。
video enhance-video-quality-generative — 生成式画质增强（云端）
基于 Diffusion 扩散大模型技术，智能补全和生成视频细节，修复压缩或老化过程中的像素损失。
video erase-subtitle-standard — 字幕擦除 (标准版)（云端）
智能检测并擦除视频画面中已有的硬字幕，保留原始背景。
video erase-subtitle-pro — 精细化字幕擦除（云端）
对视频字幕进行高质量无痕擦除，并最大程度还原视频画面。
video extract-frames — 视频抽帧（云端）
从视频中抽取截图，用于视频封面、预览图、雪碧图或其他视频理解任务的输入。
video extract-blind-watermark — 提取视频暗水印（云端）
从已嵌入暗水印的视频中解析并还原隐藏的数字信息。
video mosaic-faces — 视频人脸打码（云端）
自动精准识别视频画面中的人脸区域，并对所有人脸进行模糊或马赛克处理。
video swap-face — 视频人脸融合（云端）
将用户提供的目标人脸融合替换到视频中的人物上，输出高质量换脸视频。
video smart-cut-for-miniseries — 高光智剪-短剧（云端）
基于输入剧集的理解提取高光片段，并按要求生成高光混剪、单集预告等视频。
video smart-cut-for-game — 高光智剪-小游戏（云端）
识别小游戏录屏视频中的核心玩法与高光事件，快速生成用于买量推广的视频素材。
video smart-cut-for-long-video — 高光智剪-影视拆条（云端）
面向影视长视频，按剧情故事线识别高光并拆分成多段指定时长的高光片段。
video ultra-hd — 极智超清（云端）
在转码时智能分析视频，以相对较低码率输出主观画质更优的视频，降低带宽成本。
video cutout-green-screen — 视频绿幕抠图（本地 + 云端）
对绿幕或纯色背景的视频进行抠图，生成背景透明或纯色背景的视频。
video cutout-portrait — 视频人像抠图（云端）
自动识别视频中的人物主体，移除原始背景，生成背景透明或纯色背景的视频。
video get-meta — 视频元信息获取（本地 + 云端）
探测输入的视频 URL，输出标准化的媒资元信息。
video remux — 视频转封装（云端）
仅修改容器格式，不重新编解码音视频码流，适用于点播分发适配、流媒体切片打包等场景。
video split-by-scene — 场景切分（云端）
依据视频的转场和画面内容变化自动切分多个场景片段。
video smart-split-by-semantic — 智能语义切片（云端）
在保证语义完整的前提下，将长视频智能地切分为多个独立的素材片段。
video transcode — 视频转码（云端）
将视频码流转换为另一视频码流，可涉及编码格式、分辨率、码率等转换。
video ocr-subtitle — 视频识别字幕 (OCR)（云端）
识别输入视频画面中的字幕信息，输出带时间戳的结构化文本数据。
video smart-strategy — 视频理解智能策略（云端）
基于视觉大模型，对输入的视频 URL 列表进行通用视频内容分析，输出视频级别的结构化理解结果。
图像工具域（image）
此域包含 21 个图像处理能力，目前均仅支持云端（异步）模式。
image add-text-watermark — 添加图文水印（云端）
为图片添加图文明水印，适用于版权标识与素材分发防盗链场景。
image adjust-style — 图像调整（云端）
对输入图像的亮度、对比度和饱和度进行调整。
image compress — 图像压缩（云端）
一站式图像体积优化，覆盖压缩质量、文件体积上限、格式转换和 PNG 瘦身。
image crop — 图像裁剪（云端）
对输入图像进行多模式裁剪，可执行方向、定向、自定义或内切圆裁剪。
image enhance-quality — 图像画质增强（云端）
基于图像内容理解进行智能决策，提升图片的分辨率、清晰度与色彩表现。
image erase-and-inpaint — 图像擦除修复（云端）
按不同场景控制自动检测并擦除图片中的文字或常见图标，并通过智能填充进行修复。
image assess-quality — 图像画质评估（云端）
对输入图片进行主客观画质和美学评分，适用于质量监控、低质图筛查等场景。
image mosaic-faces — 图像人脸打码（云端）
自动检测图片中的所有人脸区域并进行马赛克处理。
image flip — 图像翻转（云端）
支持对单张图片执行水平或竖直翻转。
image gaussian-blur — 图像高斯模糊（云端）
通过设定模糊强度快速对图片进行模糊处理。
image ocr — 图像文字识别 OCR（云端）
识别图片中的简体中文和英文，并提供文本块位置坐标与置信度。
image negative — 图像负片（云端）
对输入图像执行负片（反相）效果。
image mosaic — 图像打码（云端）
支持对整张图像或指定矩形区域进行马赛克打码。
image get-meta — 图像元信息获取（云端）
支持查询 metadata、avghue、alpha、blurhash 四种图像信息。
image remove-background — 图像背景移除（云端）
自动识别并保留图像主体，移除背景后生成背景透明的图片（抠图）。
image scale — 图像缩放（云端）
支持按指定宽高、长边、短边或等比模式缩放。
image rotate — 图像旋转（云端）
通过设置旋转角度和背景样式对图片进行旋转处理。
image rounded-corners — 圆角矩形（云端）
为图片四角快速添加正圆或椭圆圆角。
image sharpen — 图像锐化（云端）
对输入图像进行锐化处理，有效增强图像的边缘细节与整体清晰度。
image smart-downsize — 集智瘦身（云端）
通过 AI 大幅缩小图片体积，修复瑕疵，增强细节，输出更轻量且更清晰的图片。
image smart-crop — 图像智能裁剪（云端）
自动识别图像中的主体人脸区域，并适配指定尺寸进行裁剪。
音频工具域（audio）
此域包含 4 个音频分析和处理能力。
audio detect-voice-activity — 语音端点识别（云端）
自动定位音频或视频文件中有效语音的起止时间，将人声和无效片段区分开。
audio get-meta — 音频元信息获取（本地 + 云端）
探测输入音频 URL，输出标准化媒资元信息。
audio separate-stem — 人声背景音分离（云端）
将音频或视频文件中的人声与背景音精准分离，输出为两个独立的音频文件。
audio transcode — 音频转码（云端）
将一个音频码流转换为另一个音频码流，用于适应不同业务场景、播放终端和网络环境。
通用辅助域（shared）
shared fetch-file — 文件下载预处理（仅限本地）
将输入的远程网络 URL 下载到本地临时目录，或验证本地文件可达性，最终统一返回一个可用的本地文件路径。此工具通常作为 Agent 编排复杂工作流时的前置步骤。
shared query-task — 任务查询（仅限云端）
常见问题
Q1：第一次使用应该按什么顺序操作？
- 安装：npm install -g @volcengine/mediakit-cli
- 初始化：mediakit-cli init --api-key <你的API_KEY> --yes
- 健康检查：mediakit-cli doctor
- 运行一个测试任务：
Q2：doctor 提示缺少 libass/libharfbuzz 等库怎么办？
doctor 提示的 brew 命令可能已过时。请参考以下方法安装全功能版的 FFmpeg。
- macOS (Homebrew):
- Ubuntu / Debian:
- Windows (Chocolatey):
Q3：作为 Agent 开发者，如何发现和使用这些能力？
- 列出能力域：mediakit-cli --domains
- 获取指定能力的 JSON Schema：mediakit-cli <domain> <tool> --schema。这个 Schema 可以直接用于构建 Function Calling 或 Tool Use 的定义。
Q4：如何获取云端异步任务的结果？
使用 shared query-task 命令，并带上 --poll-complete flag，它会一直等待直到任务完成并返回最终结果。
Q5：输出文件保存在哪里？
默认保存在 ~/.mediakit/temp/。你可以通过 --output-path flag（单次）、MEDIAKIT_OUTPUT_PATH 环境变量（会话级）或 mediakit-cli config set output-path（全局持久化）来修改。
Q6：为什么我的命令出错了，但 Shell 脚本里的 $? 还是 0？
这是当前开发版本的已知限制，部分客户端参数校验报错未能正确映射到退出码。在编写自动化脚本时，请勿仅依赖退出码判断状态。建议检查输出的 JSON 内容中是否包含 "error" 字段：
Q7：Agent 调用时，默认走云端还是本地？
默认是 cloud-first。但是，如果 MEDIAKIT_API_KEY 未配置，CLI 会静默降级到本地模式。为避免非预期的行为，建议在 Agent 或自动化脚本中显式地使用 --cloud flag，确保在未配置 Key 时能立即报错而不是悄悄降级。
最近更新时间：2026.09.08 20:09:17
这个页面对您有帮助吗？
有用
有用
无用
无用