volcengine/mediakit-cli已通过检查
SKILL DETAIL
byted-mediakit-editing
volcengine/mediakit-cli/byted-mediakit-editing
面向音频、视频或图片素材组成成片的编辑制作目标，适用于时间线裁剪与拼接、速度和音量调整、视频滤镜、运镜特效、转场、画面裁切旋转翻转、画面叠加、字幕压制、动图截取、淡入淡出、音视频提取与合流、音频混合、文字滚屏成片、图转视频以及多画面空间组合等操作。若用户要给视频添加滤镜效果，或对象和目标族已明确是对现有素材做剪辑、合成、叠加、混合或成片编排，但具体做法不确定，可先加载本 Skill 探索。
安装量 · 324查看来源
Installation
npx skills add https://github.com/volcengine/mediakit-cli --skill byted-mediakit-editing
技能文件
SKILL.md
最近同步 · 2026年9月11日
LICENSE›
# The MIT License (MIT)
Copyright © 2025 Beijing Volcano Engine Technology Ltd.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWAREreference/add-image-to-video.md›
# 视频加图片
## 能力用途
支持将指定图片（如 Logo、水印等）叠加到视频画面上。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing add-image-to-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `end_time` | `--end-time` | number | 否 | - | 最小值: 0 | 图片结束显示的时间，单位为秒。默认与视频结束时间一致。如果 end_time 超出原始视频时长，输出视频长度将延长至该 end_time，超出部分将以黑屏形式延续，图片会继续显示在黑屏上。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `start_time` | `--start-time` | number | 否 | - | 最小值: 0 | 图片开始显示的时间，单位为秒。默认与视频开始时间一致。 |
| `sub_image_height` | `--sub-image-height` | string | 否 | "5%" | 格式: "^(\\d{1,4}\|\\d{1,3}%)$" | 图片高度支持像素值或相对于视频高度的百分比，默认值为 "5%"。 |
| `sub_image_pos_x` | `--sub-image-pos-x` | string | 否 | "85%" | 格式: "^(\\d{1,4}\|\\d{1,3}%)$" | 图片左上角在水平方向（X 轴）的位置，以视频左上角 "0" 为原点，支持像素值或百分比，默认值为 "85%"。 |
| `sub_image_pos_y` | `--sub-image-pos-y` | string | 否 | "90%" | 格式: "^(\\d{1,4}\|\\d{1,3}%)$" | 图片左上角在垂直方向（Y 轴）的位置，以视频左上角 "0" 为原点，支持像素值或百分比，默认值为 "90%"。 |
| `sub_image_url` | `--sub-image-url` | string | 是 | - | - | 待添加的图片 URL。图片来源仅支持公网可访问的 HTTP/HTTPS URL。建议使用 PNG、JPG、JPEG 等常见图片格式；推荐使用带透明通道的 PNG 格式以获得最佳水印效果。 |
| `sub_image_width` | `--sub-image-width` | string | 否 | "10%" | 格式: "^(\\d{1,4}\|\\d{1,3}%)$" | 图片宽度支持像素值或相对于视频宽度的百分比，默认值为 "10%"。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待添加图片的视频 URL。视频来源支持公网 HTTP/HTTPS URL、本地文件路径、视频点播 vod:// 和对象存储 tos:// 四种输入协议。支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式，最高支持 4K（3840×2160）分辨率。建议输入文件大小不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing add-image-to-video \
--video-url <video_url> \
--sub-image-url <sub_image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频分辨率，支持 240p、360p、480p、540p、720p、1080p、2k 或 4k。 |
| `result.video_url` | string | 否 | Cloud 终态 | 添加图片后的视频文件地址。结果视频文件格式为 MP4。未设置 media_output_destination 时返回 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing add-image-to-video --help
mediakit-cli --cloud editing add-image-to-video --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing add-image-to-video`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `end_time` | `--end-time` | number | 否 | - | - | 图片的结束时间，单位：秒。注意：如果设置的开始/结束时间超出原始视频时长，输出视频长度将以该结束时间为准，超出部分以黑屏形式延续。不传默认同视频结束时间 |
| `start_time` | `--start-time` | number | 否 | - | - | 图片的开始时间，单位：秒。不传默认同视频开始时间 |
| `sub_image_height` | `--sub-image-height` | string | 否 | "5%" | - | 图片的高度，字符串类型，支持具体像素值（如 '100'）或百分比（如 '20%'，相对于视频高度）。 |
| `sub_image_pos_x` | `--sub-image-pos-x` | string | 否 | "85%" | - | 图片在水平方向（X 轴）的位置，以视频左上角为原点，字符串类型，支持具体像素值（如 '100'）或百分比（如 '20%'）。例如值为 '0' 时，表示处于最左侧。 |
| `sub_image_pos_y` | `--sub-image-pos-y` | string | 否 | "90%" | - | 图片在垂直方向（Y 轴）的位置，以视频左上角为原点，字符串类型，支持具体像素值（如 '100'）或百分比（如 '20%'）。例如值为 '0' 时，表示处于最上侧。 |
| `sub_image_url` | `--sub-image-url` | string | 是 | - | - | 图片URL。支持http://xxx或https://xxx格式 URL |
| `sub_image_width` | `--sub-image-width` | string | 否 | "10%" | - | 图片的宽度，字符串类型，支持具体像素值（如 '100'）或百分比（如 '20%'，相对于视频高度）。 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing add-image-to-video \
--video-url <video_url> \
--sub-image-url <sub_image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing add-image-to-video --help
mediakit-cli --local editing add-image-to-video --schema
```
reference/add-subtitle-to-video.md›
# 视频加字幕
## 能力用途
将字幕文件或文本内容按自定义样式压制到视频画面中，生成带内嵌字幕的新视频。
## 参数填写规则
- Cloud: subtitle_url参数与subtitles参数两者必须指定一个，且subtitle_url 优先级更高 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 设置 subtitle_pos_preset 或 subtitle_font_size 前，若没有视频宽高，先探测视频元信息。用户未指定位置时：横屏使用 bottom_center，竖屏使用 lower_third。
- 字号不得超过当前位置预设的最大渲染高度（视频原始高度 × height%）；单行字数 × 字号不得超过当前位置预设宽度（视频原始宽度 × width%）。
- 若成片用于短视频或漫剧平台，设置位置前向用户确认，并避开平台操作栏、进度条和互动控件。
- Local: 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing add-subtitle-to-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 对象或对象数组参数（`--subtitles`）需传合法 JSON 字符串并整体加单引号，例如 `--subtitles '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing add-subtitle-to-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `subtitle_font_color` | `--subtitle-font-color` | string | 否 | "#FFFFFFFF" | - | subtitle_font_color 非必填，字幕字体颜色采用 RGBA 格式，默认 #FFFFFFFF，表示不透明白色。 |
| `subtitle_font_size` | `--subtitle-font-size` | integer | 否 | 50 | 最小值: 1 | subtitle_font_size 非必填，字幕字体大小单位为 px，默认 50 px。字号不得超过所选位置预设的最大渲染高度，即视频原始高度 × height 百分比（例如 height 为 10% 时，最大字号为视频高度的 10%）；同时单行字数 × 字号不得超过所选位置预设的 width（视频原始宽度 × width 百分比，例如 80%）。 |
| `subtitle_font_type` | `--subtitle-font-type` | string | 否 | "sy_black" | 枚举: ["sy_black","pm_zhengdao","zhanku_kuaile"] | subtitle_font_type 非必填，支持 sy_black（思源黑体，经典无衬线黑体，端正百搭，正文首选）；支持 pm_zhengdao（庞门正道标题体，粗壮有力，适合大标题或封面）；支持 zhanku_kuaile（站酷快乐体，圆润活泼并带手写感，适合轻松搞笑的 Vlog 氛围）；默认 sy_black，即思源黑体。 |
| `subtitle_pos_preset` | `--subtitle-pos-preset` | string | 否 | "bottom_center" | 枚举: ["bottom_center","top_center","center","lower_third"] | subtitle_pos_preset 非必填，通过预设值快速将字幕放到画面常用位置；支持 bottom_center（底部居中，默认，推荐横屏使用）、top_center（顶部居中）、center（画面正中央）、lower_third（偏下三分之一处，推荐竖屏使用）。用户未指定位置时：横屏使用 bottom_center，竖屏使用 lower_third。各预设对应的字幕渲染区域为：top_center 为 width 80%、height 10%、pos_x 10%、pos_y 5%；center 为 width 80%、height 15%、pos_x 10%、pos_y 42.5%；lower_third 为 width 80%、height 10%、pos_x 10%、pos_y 70%；bottom_center 为 width 80%、height 10%、pos_x 10%、pos_y 85%。其中 height 为相对视频原始高度的字体渲染最大高度，width 为相对视频原始宽度的字幕区域最大宽度。若当前没有视频宽高信息，可先探测视频元信息获取宽高后再选择位置与字号。若成片用于短视频或漫剧平台，设置位置前应向用户确认，并避开对应平台的操作栏、进度条和互动控件，避免字幕被遮挡。 |
| `subtitle_url` | `--subtitle-url` | string | 否 | - | - | subtitle_url 非必填，用于提供字幕文件 URL，仅支持公网可访问的 HTTP/HTTPS URL，支持 SRT、VTT、ASS 等常见字幕格式；subtitle_url 与 subtitles 同时存在时，优先使用 subtitle_url 的内容。 |
| `subtitles` | `--subtitles` | array<object> | 否 | - | 最少项数: 0 | subtitles 非必填，是由多个字幕对象组成的字幕内容列表；每个对象包含字幕文本、开始时间和结束时间。 |
| `subtitles[].end_time` | - | number | 是 | - | 最小值: 0 | 该条字幕结束显示的时间，单位为秒。 |
| `subtitles[].start_time` | - | number | 是 | - | 最小值: 0 | 该条字幕开始显示的时间，单位为秒。 |
| `subtitles[].subtitle_text` | - | string | 是 | - | - | 单条字幕的文本内容。 |
| `video_url` | `--video-url` | string | 是 | - | - | video_url 是待添加字幕的视频 URL，支持公网 HTTP/HTTPS、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议，支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K（3840×2160）分辨率；建议输入视频文件大小不超过 10 GB。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出分辨率支持 240p、360p、480p、540p、720p、1080p、2k、4k。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的带内嵌字幕视频地址，文件格式为 MP4。设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址；未设置 media_output_destination 时，返回有效期 24 小时的 HTTPS 临时下载链接，需及时下载保存。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing add-subtitle-to-video --help
mediakit-cli --cloud editing add-subtitle-to-video --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing add-subtitle-to-video`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 使用指南
- 对象或对象数组参数（`--subtitles`）需传合法 JSON 字符串并整体加单引号，例如 `--subtitles '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing add-subtitle-to-video \
--video-url <video_url> \
--subtitle-url <subtitle_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `subtitle_font_color` | `--subtitle-font-color` | string | 否 | "#FFFFFFFF" | - | 本地字幕字体颜色，采用 RGBA 格式；默认 #FFFFFFFF，表示不透明白色。 |
| `subtitle_pos_preset` | `--subtitle-pos-preset` | string | 否 | "bottom_center" | 枚举: ["bottom_center","top_center","center","lower_third"] | 本地字幕位置。支持底部居中 bottom_center（推荐横屏）、顶部居中 top_center、画面中央 center、偏下三分之一 lower_third（推荐竖屏）；默认 bottom_center。用户未指定时横屏使用 bottom_center、竖屏使用 lower_third。各预设渲染区域：top_center 为 width 80%、height 10%、pos_x 10%、pos_y 5%；center 为 width 80%、height 15%、pos_x 10%、pos_y 42.5%；lower_third 为 width 80%、height 10%、pos_x 10%、pos_y 70%；bottom_center 为 width 80%、height 10%、pos_x 10%、pos_y 85%。若无视频宽高，可先探测视频元信息。若用于短视频或漫剧平台，应避开平台操作栏、进度条和互动控件。 |
| `subtitle_url` | `--subtitle-url` | string | 否 | - | - | 字幕文件 URL、filename。常见的字幕文件为 SRT、VTT、ASS 等格式。 |
| `subtitles` | `--subtitles` | array<object> | 否 | - | - | 字幕列表，Array<object>类型。<br>子字段说明（JSON 数组每项）:<br>- subtitle_text: 字幕文本，必填<br>- start_time: 字幕开始时间。单位：秒。必填<br>- end_time: 字幕结束时间。单位：秒。必填 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing add-subtitle-to-video --help
mediakit-cli --local editing add-subtitle-to-video --schema
```
reference/adjust-audio-speed.md›
# 音频调速
## 能力用途
用于音频调速，可调整音频播放倍速，实现快放或慢放效果。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing adjust-audio-speed`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 待调速的音频 URL。支持公网 HTTP/HTTPS URL、本地文件路径、来源于火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp3、m4a、wav 等主流音频格式；建议单个输入文件大小不超过 10 GB。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `format` | `--format` | string | 否 | "m4a" | 枚举: ["mp3","m4a","ogg","flac","wav"] | 输出音频格式。支持 mp3、m4a、ogg、flac、wav；默认值为 m4a。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `speed` | `--speed` | number | 否 | 1 | 最小值: 0.1；最大值: 4 | 音频播放倍速为 0.1 至最高 4.0；1.0 表示原速，小于 1.0 表示慢放，大于 1.0 表示快放。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing adjust-audio-speed \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.audio_url` | string | 否 | Cloud 终态 | 调速后生成的音频文件下载地址。默认未设置 media_output_destination 时返回 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存；设置 media_output_destination 后返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出音频的时长，单位为秒。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing adjust-audio-speed --help
mediakit-cli --cloud editing adjust-audio-speed --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing adjust-audio-speed`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 输入音频。支持http://xxx或https://xxx格式 Url，支持 mp3、m4a、wav 等格式 |
| `speed` | `--speed` | number | 否 | 1 | - | 调整速度的倍数，Float类型，取值范围为0.1～4。0.1=放慢至原速的 0.1 倍，1=原速，4=加速至原速的 4 倍。 |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing adjust-audio-speed \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `audio_url` | string | 否 | Local | 输出音频文件路径或 URL |
| `duration` | number | 否 | Local | 音频时长，单位：秒 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing adjust-audio-speed --help
mediakit-cli --local editing adjust-audio-speed --schema
```
reference/adjust-video-speed.md›
# 视频调速
## 能力用途
用于视频调速，通过调整播放倍速产生快放或慢放效果。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing adjust-video-speed`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `speed` | `--speed` | number | 否 | 1 | 最小值: 0.1；最大值: 4 | 播放速度倍数，取值范围 0.1～4.0，默认值为 1.0，表示原速；大于 1.0 表示快放，小于 1.0 表示慢放。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待调速视频的 URL。支持公网 HTTP/HTTPS、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K（3840×2160）分辨率；建议输入文件大小不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing adjust-video-speed \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率，支持 240p、360p、480p、540p、720p、1080p、2k、4k。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的调速后视频文件地址，文件格式为 MP4。未设置 media_output_destination 时，返回有效期 24 小时的 HTTPS 临时下载链接，需要及时下载保存；设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing adjust-video-speed --help
mediakit-cli --cloud editing adjust-video-speed --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing adjust-video-speed`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `speed` | `--speed` | number | 否 | 1 | - | 调整速度的倍数，Float类型，取值范围为0.1～4。 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing adjust-video-speed \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing adjust-video-speed --help
mediakit-cli --local editing adjust-video-speed --schema
```
reference/adjust-video-volume.md›
# 调整视频音量
## 能力用途
用于调整输入视频的音量大小，也可实现静音。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing adjust-video-volume`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待处理的视频 URL。支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K（3840×2160）分辨率；建议单个输入文件大小不超过 10 GB。 |
| `volume` | `--volume` | number | 否 | 1 | 最小值: 0；最大值: 4 | 音量调整倍数，非必填，可省略；需使用浮点数，范围为 0 到 4。0 表示静音，1 表示保持原音量；小于 1 表示减小音量，大于 1 表示放大音量。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing adjust-video-volume \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率（如 720p、1080p、2k、4k 等），与原视频保持一致。 |
| `result.video_url` | string | 否 | Cloud 终态 | 处理后的视频文件地址，文件格式为 MP4。未设置 media_output_destination 时，返回 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后，返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing adjust-video-volume --help
mediakit-cli --cloud editing adjust-video-volume --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing adjust-video-volume`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。支持http://xxx或https://xxx格式 URL，支持 mp4、mov、flv、ts、avi、wmv、mkv 等格式，最高 4K |
| `volume` | `--volume` | number | 否 | 1 | - | 音量倍数。Float 类型，取值范围 0~4。0=静音，1=原音量，4=放大 4 倍。 |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing adjust-video-volume \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing adjust-video-volume --help
mediakit-cli --local editing adjust-video-volume --schema
```
reference/apply-camera-motion.md›
# 视频添加运镜
## 能力用途
对输入视频在指定时间段内添加一种运镜特效，常用于素材二次创作、营销片头、短剧动效等场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing apply-camera-motion`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数；任务完成时会通过事件回调原样返回，用于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址；提供后优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制；大小写敏感，长度不超过 64 个 ASCII 可打印字符。 默认不传。用户明确指定时原样使用；用户明确要求重试时，同一逻辑请求的重试链必须复用同一 token。已有 token 时必须复用原值；此前请求未带 token 时，可从本次重试开始创建一次并持续复用，但该 token 不对此前请求提供追溯幂等。业务参数变化视为新请求，不得复用旧 token。不得为每次尝试生成不同值。CLI/MCP runtime 不判断重试意图，也不自动生成 token。 |
| `end_time` | `--end-time` | number | 否 | - | 最小值: 0 | 运镜结束时间，单位为秒，支持设置为 2 位小数，需大于 start_time；默认到视频结尾；仅传 start_time 时会运镜到视频结尾；若填写值超过视频实际时长，将自动按视频时长处理。 |
| `motion_style` | `--motion-style` | string | 否 | "zoom" | 枚举: ["zoom","pan-zoom","orbit-360","bounce"] | 运镜风格，支持 zoom、pan-zoom、orbit-360、bounce 几种预设效果，默认值为 zoom。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID；不传时默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以按队列对应的项目进行分账。队列可创建和管理，系统会自动分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `start_time` | `--start-time` | number | 否 | 0 | 最小值: 0 | 运镜开始时间，单位为秒，支持设置为 2 位小数，不得小于 0；默认值为 0，0 表示从视频片头开始；仅传 end_time 时按 0 作为开始时间。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待处理的视频 URL。支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等格式；最高支持 1080p 分辨率；视频时长不得超过 5 分钟。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing apply-camera-motion \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 任务结果查询
提交成功后会返回 `task_id`，再执行 `mediakit-cli shared query-task --task-id <task_id>` 查询。
- 当前命令：`mediakit-cli editing apply-camera-motion`
- 推荐查询：`mediakit-cli shared query-task --task-id <task_id>`
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing apply-camera-motion --help
mediakit-cli editing apply-camera-motion --schema
```
reference/apply-video-filter.md›
# 视频添加滤镜
## 能力用途
为指定视频添加滤镜效果。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing apply-video-filter`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `filter_style` | `--filter-style` | string | 否 | "spring" | 枚举: ["spring","sunset","vivid","fair_skin","food"] | 滤镜风格，必须选择 spring、sunset、vivid、fair_skin、food 之一；默认 spring（春日滤镜）。spring 表示春日滤镜，sunset 表示晚霞滤镜，vivid 表示鲜亮滤镜，fair_skin 表示白皙滤镜，food 表示食物滤镜。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待处理视频 URL。支持公网 HTTP/HTTPS URL、本地文件路径、视频点播 vod:// 和对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K（3840×2160）分辨率；建议单个输入文件大小不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing apply-video-filter \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率，如 720p、1080p、2k、4k 等。 |
| `result.video_url` | string | 否 | Cloud 终态 | 处理后的视频文件地址，文件格式为 MP4。未设置 media_output_destination 时，返回 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后，返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing apply-video-filter --help
mediakit-cli editing apply-video-filter --schema
```
reference/concat-audio.md›
# 音频拼接
## 能力用途
拼接多个音频片段。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing concat-audio`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--audio-urls`）传多个值时用逗号分隔并整体加引号，例如 `--audio-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing concat-audio \
--audio-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_urls` | `--audio-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 100 | 待拼接的音频 URL 列表；单次任务最少传入 1 个 URL，最多传入 100 个 URL；支持 mp3、m4a、wav 等主流音频格式；音频来源支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；建议单个输入文件大小不超过 10 GB。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `format` | `--format` | string | 否 | "m4a" | 枚举: ["mp3","m4a","ogg","flac","wav"] | 输出音频格式支持 mp3、m4a、ogg、flac、wav；默认值为 m4a。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.audio_url` | string | 否 | Cloud 终态 | 生成的拼接音频文件地址。未设置 media_output_destination 时，audio_url 返回一个 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后，audio_url 返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出音频的总时长，单位为秒。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing concat-audio --help
mediakit-cli --cloud editing concat-audio --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing concat-audio`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 使用指南
- 数组参数（`--audio-urls`）传多个值时用逗号分隔并整体加引号，例如 `--audio-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing concat-audio \
--audio-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_urls` | `--audio-urls` | array<string> | 是 | - | - | 待拼接的音频列表，Array<string>类型。最少传入1个，最多传入100个<br>子项说明：待拼接的输入音频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `audio_url` | string | 否 | Local | 输出音频文件路径或 URL |
| `duration` | number | 否 | Local | 音频时长，单位：秒 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing concat-audio --help
mediakit-cli --local editing concat-audio --schema
```
reference/concat-video.md›
# 视频拼接
## 能力用途
将多个视频按顺序拼接成一个完整的视频文件，并支持在拼接处添加转场效果。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing concat-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--transitions`、`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--transitions "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing concat-video \
--video-urls <video_urls>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `transitions` | `--transitions` | array<string> | 否 | - | 元素枚举: ["1182359","1182360","1182358","1182365","1182367","1182368","1182369","1182370","1182373","1182374","1182375","1182378"] | 视频间的转场效果 ID 列表；默认无转场（硬切）。当视频数量超过转场数量 2 个及以上时，系统将自动循环使用转场。 转场效果 ID 分类：交替出场，ID：1182359 分类：旋转放大，ID：1182360 分类：泛开，ID：1182358 分类：六角形，ID：1182365 分类：故障转换，ID：1182367 分类：飞眼，ID：1182368 分类：梦幻放大，ID：1182369 分类：开门展现，ID：1182370 分类：立方转换，ID：1182373 分类：透镜变换，ID：1182374 分类：晚霞转场，ID：1182375 分类：圆形交替，ID：1182378 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 100 | 待拼接的视频 URL 列表，单次任务支持传入 1 到 100 个 URL；建议单个输入文件大小不超过 10 GB；输入视频最高支持 4K (3840×2160) 分辨率；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。当输入多个分辨率不一致的视频时，输出视频的分辨率以列表中第一个视频为基准。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的拼接视频文件地址，对应文件格式为 MP4。未设置 media_output_destination 时，返回一个 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后，返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing concat-video --help
mediakit-cli --cloud editing concat-video --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing concat-video`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 使用指南
- 数组参数（`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--video-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing concat-video \
--video-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `video_urls` | `--video-urls` | array<string> | 是 | - | - | 待拼接的视频列表，Array<string>类型。最少传入1个，最多传入100个<br>子项说明：待拼接的输入视频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing concat-video --help
mediakit-cli --local editing concat-video --schema
```
reference/crop-video.md›
# 视频画面裁剪
## 能力用途
按指定的矩形区域裁剪视频画面，裁剪结果仅保留指定的需要区域。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing crop-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `bottom_right_x` | `--bottom-right-x` | integer | 是 | - | 最小值: 1 | 裁剪矩形右下角的 X 坐标，单位为像素。bottom_right_x 必须大于 top_left_x，且 bottom_right_x 与 top_left_x 的差值不得小于 16px。建议裁剪矩形不要超出原始画面边界；当 bottom_right_x 超过视频宽度或 bottom_right_y 超过视频高度时，裁剪结果的相应维度会截断至画面边界。 |
| `bottom_right_y` | `--bottom-right-y` | integer | 是 | - | 最小值: 1 | 裁剪矩形右下角的 Y 坐标，单位为像素。bottom_right_y 必须大于 top_left_y，且 bottom_right_y 与 top_left_y 的差值不得小于 16px。建议裁剪矩形不要超出原始画面边界；当 bottom_right_x 超过视频宽度或 bottom_right_y 超过视频高度时，裁剪结果的相应维度会截断至画面边界。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `top_left_x` | `--top-left-x` | integer | 是 | - | 最小值: 0 | top_left_x 是裁剪矩形左上角的水平方向 X 坐标，单位为像素。top_left_x 必须为非负整数。 |
| `top_left_y` | `--top-left-y` | integer | 是 | - | 最小值: 0 | top_left_y 是裁剪矩形左上角的垂直方向 Y 坐标，单位为像素。top_left_y 必须为非负整数。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待裁剪视频的 URL。支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；支持公网 HTTP/HTTPS、本地文件路径、火山引擎视频点播 vod:// 和对象存储 tos:// 四种输入协议。输入视频最高支持 4K（3840×2160）分辨率，建议输入文件大小不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing crop-video \
--video-url <video_url> \
--top-left-x <top_left_x> \
--top-left-y <top_left_y> \
--bottom-right-x <bottom_right_x> \
--bottom-right-y <bottom_right_y>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率，支持 240p、360p、480p、540p、720p、1080p、2k、4k。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的裁剪后视频文件地址。生成的裁剪后视频文件格式为 MP4。未设置 media_output_destination 时，返回有效期 24 小时的 HTTPS 临时下载链接，需要及时下载保存；设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing crop-video --help
mediakit-cli editing crop-video --schema
```
reference/extract-animated-image.md›
# 视频截取动图
## 能力用途
从视频中按指定开始时间和结束时间截取一段画面，生成 GIF 或 WebP 动图，常用于制作封面动图、营销素材和短预览。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing extract-animated-image`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `end_time` | `--end-time` | number | 是 | - | 最小值: 0 | end_time 表示截取片段的结束时间，单位为秒；end_time 必须大于 start_time；输出动图的时长最大为 60 秒；end_time 支持最多 3 位小数。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的对象存储（TOS）桶，可设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要授权 AI MediaKit 将文件写入您的 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `output_format` | `--output-format` | string | 否 | "gif" | 枚举: ["gif","webp"] | output_format 支持 gif 和 webp，默认值为 gif。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `start_time` | `--start-time` | number | 是 | 0 | 最小值: 0 | start_time 表示截取片段的开始时间，单位为秒；start_time 默认为 0，表示从视频开头截取；start_time 支持最多 3 位小数。 |
| `video_url` | `--video-url` | string | 是 | - | - | video_url 指定待截取动图的视频 URL；video_url 支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；输入视频支持 mp4、flv、ts、avi、mov、wmv、mkv 等格式，最高支持 4K（3840×2160）分辨率。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing extract-animated-image \
--video-url <video_url> \
--start-time <start_time> \
--end-time <end_time>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | duration 表示输出动图的时长，单位为秒，根据 min(end_time, 视频总时长) - start_time 计算得出，保留 3 位小数。 |
| `result.image_url` | string | 否 | Cloud 终态 | image_url 是生成的动图文件地址，输出动图的帧率固定为 15 fps。未设置 media_output_destination 时，image_url 返回有效期为 24 小时的 HTTPS 临时下载链接，需及时下载保存；设置 media_output_destination 后，image_url 返回格式为 tos://<桶名>/<对象Key> 的存储地址。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输入视频的分辨率低于 480p 时，输出动图的 resolution 对齐输入视频；输出动图的 resolution 最大为 480p。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing extract-animated-image --help
mediakit-cli editing extract-animated-image --schema
```
reference/extract-audio.md›
# 提取音频
## 能力用途
从输入视频文件中分离音轨，生成独立的音频文件。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing extract-audio`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `format` | `--format` | string | 否 | "m4a" | 枚举: ["mp3","m4a","ogg","flac","wav"] | 输出音频格式支持 mp3、m4a、ogg、flac、wav，默认值为 m4a。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待提取音频的视频 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod://、火山引擎对象存储 tos:// 四种输入协议；建议单个输入文件大小不超过 10 GB；输入视频最高支持 4K (3840×2160) 分辨率；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing extract-audio \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.audio_url` | string | 否 | Cloud 终态 | 提取出的音频文件下载地址。默认情况下返回一个 HTTPS 临时下载链接，有效期为 24 小时；指定输出存储位置后返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出音频的总时长，单位为秒。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing extract-audio --help
mediakit-cli --cloud editing extract-audio --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing extract-audio`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `format` | `--format` | string | 否 | "m4a" | 枚举: ["mp3","m4a"] | 输出音频的格式，支持 mp3、m4a 格式。 默认m4a |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频，String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing extract-audio \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `audio_url` | string | 否 | Local | 输出音频文件路径或 URL |
| `duration` | number | 否 | Local | 音频时长，单位：秒 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing extract-audio --help
mediakit-cli --local editing extract-audio --schema
```
reference/fade-audio.md›
# 音频声音淡入淡出
## 能力用途
对输入音频的起止位置实现淡入或淡出效果，输出处理后的音频文件。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing fade-audio`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 输入音频，支持 mp3、m4a、wav 等主流音频格式；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；建议单个输入文件大小不超过 10 GB。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `fade_in_duration` | `--fade-in-duration` | number | 否 | 1 | 最小值: 0 | 声音淡入时长，单位为秒，支持最多 3 位小数，默认值为 1；为 0 或不填时不执行淡入操作。 |
| `fade_out_duration` | `--fade-out-duration` | number | 否 | 1 | 最小值: 0 | 声音淡出时长，单位为秒，支持最多 3 位小数，默认值为 1；为 0 或不填时不执行淡出操作。 |
| `format` | `--format` | string | 否 | "mp3" | 枚举: ["mp3","m4a","ogg","flac","wav"] | 输出音频格式，支持 mp3、m4a、ogg、flac、wav。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing fade-audio \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.audio_url` | string | 否 | Cloud 终态 | 处理后的音频文件地址。未设置 media_output_destination 时，返回 HTTPS 临时下载链接；默认返回的 HTTPS 临时下载链接有效期为 24 小时，请及时下载保存。设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出音频的总时长，单位为秒。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing fade-audio --help
mediakit-cli --cloud editing fade-audio --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing fade-audio`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 输入音频。支持http://xxx或https://xxx格式 URL，支持 mp3、m4a、wav、flac 等格式 |
| `fade_in_duration` | `--fade-in-duration` | number | 否 | 1 | - | 声音淡入时长。单位：秒，可传小数（最多3位小数）。0 表示不淡入。 |
| `fade_out_duration` | `--fade-out-duration` | number | 否 | 1 | - | 声音淡出时长。单位：秒，可传小数（最多3位小数）。0 表示不淡出。 |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing fade-audio \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `audio_url` | string | 否 | Local | 输出音频文件路径或 URL |
| `duration` | number | 否 | Local | 音频时长，单位：秒 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing fade-audio --help
mediakit-cli --local editing fade-audio --schema
```
reference/fade-video-audio.md›
# 视频声音淡入淡出
## 能力用途
在片头或片尾对输入视频音轨执行淡入或淡出处理，用于弱化音轨突兀的起止，提升成片听感。输出处理后的视频文件。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing fade-video-audio`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `fade_in_duration` | `--fade-in-duration` | number | 否 | 1 | 最小值: 0 | 声音淡入时长，单位为秒，默认值为 1，支持最多 3 位小数；取 0 时不执行淡入操作。 |
| `fade_out_duration` | `--fade-out-duration` | number | 否 | 1 | 最小值: 0 | 声音淡出时长，单位为秒，默认值为 1，支持最多 3 位小数；取 0 时不执行淡出操作。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待处理的视频 URL。支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K（3840×2160）分辨率；建议单个输入文件大小不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing fade-video-audio \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率，与原视频保持一致，可表示为 720p、1080p、2k、4k 等。 |
| `result.video_url` | string | 否 | Cloud 终态 | 处理后的视频文件地址。处理后的视频文件格式为 MP4。未设置 media_output_destination 时，返回有效期为 24 小时的 HTTPS 临时下载链接，请及时下载保存；设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing fade-video-audio --help
mediakit-cli --cloud editing fade-video-audio --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing fade-video-audio`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `fade_in_duration` | `--fade-in-duration` | number | 否 | 1 | - | 声音淡入时长。单位：秒，可传小数（最多3位小数）。0 表示不淡入。 |
| `fade_out_duration` | `--fade-out-duration` | number | 否 | 1 | - | 声音淡出时长。单位：秒，可传小数（最多3位小数）。0 表示不淡出。 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。支持http://xxx或https://xxx格式 URL，支持 mp4、mov、flv、ts、avi、wmv、mkv 等格式，最高 4K |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing fade-video-audio \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing fade-video-audio --help
mediakit-cli --local editing fade-video-audio --schema
```
reference/flip-video.md›
# 视频画面翻转
## 能力用途
用于视频画面翻转，对指定视频进行上下或左右镜像翻转。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing flip-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--is-flip-horizontal`、`--is-flip-vertical`）只能写成 `--is-flip-horizontal=true` 或 `--is-flip-horizontal=false`，也可用裸 `--is-flip-horizontal`（等价 true）；禁止空格传值 `--is-flip-horizontal true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing flip-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `is_flip_horizontal` | `--is-flip-horizontal` | boolean | 否 | false | - | 可省略，用于控制是否进行水平（左右）翻转，默认值为 false。 |
| `is_flip_vertical` | `--is-flip-vertical` | boolean | 否 | false | - | 可省略，用于控制是否进行垂直（上下）翻转，默认值为 false。is_flip_vertical 和 is_flip_horizontal 两个参数至少需要将其中一个设置为 true，否则处理后的视频与原视频没有区别；如果两个参数都设置为 true，效果等同于将画面旋转 180 度。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待翻转的视频 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K (3840×2160) 分辨率；建议输入文件大小不超过 10 GB。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率，可能为 240p、360p、480p、540p、720p、1080p、2k 或 4k。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的翻转后视频文件地址，文件格式为 MP4。未设置 media_output_destination 时返回一个 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing flip-video --help
mediakit-cli --cloud editing flip-video --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing flip-video`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 使用指南
- 布尔参数（`--is-flip-horizontal`、`--is-flip-vertical`）只能写成 `--is-flip-horizontal=true` 或 `--is-flip-horizontal=false`，也可用裸 `--is-flip-horizontal`（等价 true）；禁止空格传值 `--is-flip-horizontal true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing flip-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `is_flip_horizontal` | `--is-flip-horizontal` | boolean | 否 | false | - | 是否进行水平翻转。Boolean 类型，默认值为 false， 表示不翻转。 |
| `is_flip_vertical` | `--is-flip-vertical` | boolean | 否 | false | - | 是否进行垂直翻转。Boolean 类型，默认值为 false， 表示不翻转。 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing flip-video --help
mediakit-cli --local editing flip-video --schema
```
reference/image-to-video.md›
# 图片转视频
## 能力用途
将多张图片按顺序组合成动态视频，可配置转场动画和镜头内动画；仅把现有图片做成带动效的视频，不支持根据参考图生成新的画面内容。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing image-to-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--transitions`）传多个值时用逗号分隔并整体加引号，例如 `--transitions "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--images`）需传合法 JSON 字符串并整体加单引号，例如 `--images '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing image-to-video \
--images '[{...}]'
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `images` | `--images` | array<object> | 是 | - | 最少项数: 1；最多项数: 100 | 图片对象列表，用于定义视频的每一帧内容；单次任务支持最少 1 个、最多 100 个图片对象。 |
| `images[].animation_in` | - | number | 否 | - | - | 仅在设置了 animation_type 后生效；动画开始时间点相对于该图片片段的起始，单位：秒；默认值为 0，表示动画从图片展示的第一帧开始。 |
| `images[].animation_out` | - | number | 否 | - | - | 仅在设置了 animation_type 后生效；动画结束时间点相对于该图片片段的起始，单位：秒；默认值为图片的 duration 值，表示动画在图片展示的最后一帧结束。 |
| `images[].animation_type` | - | string | 否 | - | - | 图片展示期间的镜头内动画类型；默认无动画；可使用 move_up、move_down、move_left、move_right、zoom_in、zoom_out。 |
| `images[].duration` | - | number | 否 | - | - | 图片展示时长，单位：秒；默认值为 3；支持最多两位小数。 |
| `images[].image_url` | - | string | 是 | - | - | 图片的 URL；支持公网 HTTP/HTTPS URL、本地文件路径、对象存储 tos:// 三种输入协议；支持 jpg、png 等主流静态图片格式。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `transitions` | `--transitions` | array<string> | 否 | - | 元素枚举: ["1182359","1182360","1182358","1182365","1182367","1182368","1182369","1182370","1182373","1182374","1182375","1182378"] | 图片间的转场效果 ID 列表；默认无转场（硬切）；如果列表长度小于所需转场数（图片数量 - 1），将循环使用列表中的效果。 转场效果 ID 分类：交替出场，ID：1182359 分类：旋转放大，ID：1182360 分类：泛开，ID：1182358 分类：六角形，ID：1182365 分类：故障转换，ID：1182367 分类：飞眼，ID：1182368 分类：梦幻放大，ID：1182369 分类：开门展现，ID：1182370 分类：立方转换，ID：1182373 分类：透镜变换，ID：1182374 分类：晚霞转场，ID：1182375 分类：圆形交替，ID：1182378 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位：秒 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的视频文件地址，视频文件格式为 MP4；设置 media_output_destination 后返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>；未设置 media_output_destination 时默认返回 HTTPS 临时下载链接，有效期为 24 小时。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing image-to-video --help
mediakit-cli editing image-to-video --schema
```
reference/mix-audio.md›
# 音频混合
## 能力用途
将多个音频文件（如背景音乐、音效、人声）进行混音，生成一个新的音频文件。
处理耗时：处理耗时与视频时长正相关。视频时长越长，处理耗时越长。平均 RTF（处理耗时/原片时长）为 1。
输出音频的时长以最长的音频为准。
输出视频格式：mp3
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing mix-audio`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--audio-urls`）传多个值时用逗号分隔并整体加引号，例如 `--audio-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing mix-audio \
--audio-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_urls` | `--audio-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 100 | 待混合的音频列表，必须提供 1 到 100 个音频；单个输入文件大小建议不超过 10 GB；支持 mp3、wav、flac 等主流音频格式；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `format` | `--format` | string | 否 | "m4a" | 枚举: ["mp3","m4a","ogg","flac","wav"] | 输出音频格式，可选；支持 mp3、m4a、ogg、flac、wav，默认 m4a。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.audio_url` | string | 否 | Cloud 终态 | 混合后生成的音频文件下载地址；未设置 media_output_destination 时，返回有效期为 24 小时的 HTTPS 临时下载链接；设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出音频的时长，单位为秒，以所有输入音频中最长的一个为准。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing mix-audio --help
mediakit-cli --cloud editing mix-audio --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing mix-audio`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 使用指南
- 数组参数（`--audio-urls`）传多个值时用逗号分隔并整体加引号，例如 `--audio-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing mix-audio \
--audio-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_urls` | `--audio-urls` | array<string> | 是 | - | - | 待混合的音频列表，Array<string>类型。最少传入1个，最多传入100个。<br>子项说明：待混合的输入音频。支持http://xxx或https://xxx格式 URL，支持 mp3、wav、flac 等格式 |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `audio_url` | string | 否 | Local | 输出音频文件路径或 URL |
| `duration` | number | 否 | Local | 音频时长，单位：秒 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing mix-audio --help
mediakit-cli --local editing mix-audio --schema
```
reference/mux-audio-video.md›
# 视频加音频
## 能力用途
可将输入的音频流与视频流合并成一个新的视频文件，并可选择保留或替换视频的原有音轨；当音视频时长不一致时，可进行对齐处理。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing mux-audio-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--is-audio-reserve`、`--is-video-audio-sync`）只能写成 `--is-audio-reserve=true` 或 `--is-audio-reserve=false`，也可用裸 `--is-audio-reserve`（等价 true）；禁止空格传值 `--is-audio-reserve true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing mux-audio-video \
--video-url <video_url> \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 输入音频的 URL，支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 和 tos:// 四种输入协议；支持 mp3、m4a、wav 等主流音频格式；建议单个音频输入文件大小不超过 10 GB。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `is_audio_reserve` | `--is-audio-reserve` | boolean | 否 | true | - | 可选，用于控制是否保留原视频中的原音轨；默认值为 true，即保留原音轨；为 true 时新音频将与原音频混音；为 false 时不保留原音轨，用新音频替换原有音频。 |
| `is_video_audio_sync` | `--is-video-audio-sync` | boolean | 否 | false | - | 可选，默认值为 false，即不对齐；为 false 时合成视频的时长以较长的媒体流为准；为 true 时根据 sync_mode 和 sync_method 的配置进行对齐处理。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `sync_method` | `--sync-method` | string | 否 | "trim" | - | 可选，仅在 is_video_audio_sync 为 true 时生效，用于指定时长对齐方式；默认值为 trim（裁剪）；为 trim 时将较长的媒体流从末尾裁剪，使其与较短的对齐；为 speed 时通过加速或减速使两个媒体流时长一致。 |
| `sync_mode` | `--sync-mode` | string | 否 | "video" | - | 可选，仅在 is_video_audio_sync 为 true 时生效，作为音视频时长对齐基准；默认值为 video，以视频时长为准；为 audio 时以音频时长为准，如视频更长则裁剪视频，如视频更短则根据 sync_method 处理；为 video 时，如音频更长则裁剪音频，如音频更短则根据 sync_method 处理。 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频的 URL，支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 和 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K (3840×2160) 分辨率；建议单个视频输入文件大小不超过 10 GB。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | duration 表示输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | resolution 表示输出视频的分辨率。 |
| `result.video_url` | string | 否 | Cloud 终态 | video_url 为合成后的视频文件下载地址，文件格式为 MP4；未设置 media_output_destination 时返回 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing mux-audio-video --help
mediakit-cli --cloud editing mux-audio-video --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing mux-audio-video`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 输入音频。String 类型，支持http://xxx或https://xxx格式 URL |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing mux-audio-video \
--video-url <video_url> \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing mux-audio-video --help
mediakit-cli --local editing mux-audio-video --schema
```
reference/rotate-video.md›
# 视频画面旋转
## 能力用途
用于视频画面旋转，对指定视频进行整体旋转。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing rotate-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `rotate_direction` | `--rotate-direction` | string | 是 | - | 枚举: ["rotate_left_90","rotate_right_90","rotate_180"] | 旋转方式，支持 rotate_left_90、rotate_right_90、rotate_180：rotate_left_90 表示向左旋转 90 度，rotate_right_90 表示向右旋转 90 度，rotate_180 表示旋转 180 度。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待旋转的视频 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K (3840×2160) 分辨率；建议输入文件大小不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing rotate-video \
--video-url <video_url> \
--rotate-direction <rotate_direction>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率，可能为 240p、360p、480p、540p、720p、1080p、2k、4k。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的旋转后视频文件下载地址，文件格式为 MP4。默认情况（未设置 media_output_destination）时，返回 HTTPS 临时下载链接，有效期为 24 小时；设置 media_output_destination 后，返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing rotate-video --help
mediakit-cli editing rotate-video --schema
```
reference/stitch-video.md›
# 视频画面拼接
## 能力用途
将多个视频在空间上按水平或垂直方向拼接成一个完整画面，适用于多视角对比、画面组合等场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing stitch-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 对象或对象数组参数（`--videos`）需传合法 JSON 字符串并整体加单引号，例如 `--videos '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing stitch-video \
--videos '[{...}]'
--stitch-direction <stitch_direction>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `stitch_direction` | `--stitch-direction` | string | 是 | - | 枚举: ["horizontal","vertical"] | 拼接方式：horizontal 表示左右拼接，vertical 表示上下拼接。 |
| `videos` | `--videos` | array<object> | 是 | - | 最少项数: 2；最多项数: 3 | 待拼接的视频对象列表，最少传入 2 个，最多传入 3 个；拼接画面的顺序与列表顺序一致。 |
| `videos[].keep_audio` | - | boolean | 否 | true | - | 是否保留该视频的音频。默认值 true；为 false 时，该视频的音轨不会被合入最终产物。 |
| `videos[].video_url` | - | string | 是 | - | - | 待拼接的输入视频地址。支持公网 HTTP/HTTPS、本地文件路径、视频点播 vod://、对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。输入视频最高支持 4K (3840×2160) 分辨率。建议输入文件大小不超过 10 GB。建议输入视频的宽高比为 16:9、9:16、1:1、4:3、3:4 等常见规格，以获得更好的拼接效果。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频分辨率可能为 240p、360p、480p、540p、720p、1080p、2k 或 4k。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的拼接后视频文件地址，文件格式为 MP4。未设置输出存储位置时，返回 HTTPS 临时下载链接，有效期为 24 小时；设置输出存储位置后，返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing stitch-video --help
mediakit-cli editing stitch-video --schema
```
reference/text-to-scrolling-video.md›
# 文字生成滚屏视频
## 能力用途
将指定文本内容转换为文字滚屏视频，输出视频为固定 9:16 竖版，常用于小说推文、内容讲解和歌词视频等场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli editing text-to-scrolling-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 否 | - | - | 背景音乐 URL。支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 火山引擎视频点播和 tos:// 火山引擎对象存储四种输入协议，支持 mp3、m4a、wav 等主流音频格式。建议单个输入音频文件不超过 10 GB。提供背景音乐后，会无缝循环播放并覆盖整个视频时长，直到视频结束；若背景音乐时长超过视频时长，超出部分会自动截断。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `end_hold_duration` | `--end-hold-duration` | number | 否 | 2 | 最小值: 0；最大值: 60 | 视频结束时，文字在结束位置静止停留的时长，单位为秒，范围 0 到 60，默认 2。 |
| `font_color` | `--font-color` | string | 否 | "#1F1F1FFF" | 格式: "^#[0-9A-Fa-f]{8}$" | 字体颜色必须采用 8 位 RGBA 十六进制 RRGGBBAA 格式，默认 #1F1F1FFF，表示不透明深灰色。使用深色背景图时，建议传入浅色字体（如 #FFFFFFFF）以保证可读性。 |
| `font_type` | `--font-type` | string | 否 | "sy_black" | 枚举: ["sy_black","pm_zhengdao","zhanku_kuaile"] | 滚屏文本字体支持 sy_black、pm_zhengdao、zhanku_kuaile，默认 sy_black。sy_black 表示思源黑体，风格经典、端正、百搭；pm_zhengdao 表示庞门正道标题体，风格粗壮、有力；zhanku_kuaile 表示站酷快乐体，风格圆润、活泼。 |
| `image_url` | `--image-url` | string | 是 | - | - | 背景图片 URL。支持公网 HTTP/HTTPS URL、本地文件路径和 tos:// 火山引擎对象存储三种输入协议，支持 jpg、png 等主流静态图片格式。建议背景图片宽高比为 9:16，与输出视频一致；建议背景图片分辨率尽量与 resolution 选择的输出视频分辨率一致；建议背景图片整体基调与 font_color 形成足够对比度。系统自动裁切背景图片顶部 10% 和底部 10% 区域，裁切区域作为半透明遮罩叠加在视频顶部和底部，增强滚屏文字可读性；建议背景图片顶部和底部各 10% 区域不包含关键信息。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `resolution` | `--resolution` | string | 否 | "720p" | 枚举: ["360p","480p","720p","1080p"] | 输出分辨率选择固定 9:16 的竖版规格，支持 360p、480p、720p、1080p，默认 720p。360p 对应 360 × 640 像素输出尺寸，480p 对应 480 × 854 像素输出尺寸，720p 对应 720 × 1280 像素输出尺寸且为默认档位，1080p 对应 1080 × 1920 像素输出尺寸。字体大小随 resolution 档位线性缩放，以保持视觉效果一致；在 720p 分辨率下，字号约为 36px。 |
| `single_roll_duration` | `--single-roll-duration` | number | 否 | 3 | 最小值: 0.5；最大值: 60 | 单页文字从进入画面到完全滚出画面所需时间，也表示单页文字完全滚过屏幕的时长，单位为秒，范围 0.5 到 60，默认 3。single_roll_duration 越小，滚动速度越快。 |
| `start_hold_duration` | `--start-hold-duration` | number | 否 | 2 | 最小值: 0；最大值: 60 | 视频开始时，文字在起始位置静止停留的时长，单位为秒，范围 0 到 60，默认 2。 |
| `text` | `--text` | string | 是 | - | 最短长度: 1 | 滚屏文本内容，支持使用 \n 强制换行；未包含 \n 时，文本会按画布宽度自动换行。文本横排、左对齐显示。若要显示单个斜杠 /，传入 text 时需输入两个斜杠 //。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli editing text-to-scrolling-video \
--text <text> \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频总时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频分辨率。 |
| `result.video_url` | string | 否 | Cloud 终态 | 生成的文字滚屏视频文件地址，视频文件格式为 MP4。设置 media_output_destination 后，为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 存储地址；未设置 media_output_destination 时，为有效期 24 小时的 HTTPS 临时下载链接。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli editing text-to-scrolling-video --help
mediakit-cli editing text-to-scrolling-video --schema
```
reference/trim-audio.md›
# 音频裁剪
## 能力用途
用于音频裁剪，按指定的开始时间和结束时间从输入音频中截取片段。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing trim-audio`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 待裁剪音频的 URL，支持 mp3、m4a、wav 等主流音频格式，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；建议单个输入文件大小不超过 10 GB。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `end_time` | `--end-time` | number | 否 | - | 最小值: 0 | 裁剪结束时间，单位为秒，支持最多两位小数；必须大于 start_time；end_time 可省略，不传时默认裁剪到输入音频末尾。 |
| `format` | `--format` | string | 否 | "m4a" | 枚举: ["mp3","m4a","ogg","flac","wav"] | 输出音频格式支持 mp3、m4a、ogg、flac、wav，默认值为 m4a。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `start_time` | `--start-time` | number | 否 | 0 | 最小值: 0 | 裁剪开始时间，单位为秒，默认值为 0，0 表示从音频开头开始；支持最多两位小数；必须小于 end_time。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing trim-audio \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.audio_url` | string | 否 | Cloud 终态 | 生成的 audio_url 音频文件下载地址；设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址；未设置 media_output_destination 时，返回有效期为 24 小时的 HTTPS 临时下载链接，请及时下载保存。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出音频的总时长，单位为秒。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing trim-audio --help
mediakit-cli --cloud editing trim-audio --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing trim-audio`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 是 | - | - | 输入纯音频。String 类型，支持http://xxx或https://xxx格式 URL |
| `end_time` | `--end-time` | number | 否 | - | - | 裁剪结束时间，默认为片源结尾。支持设置为 2 位小数，单位：秒。 |
| `start_time` | `--start-time` | number | 否 | 0 | - | 裁剪开始时间，默认为 0， 表示从头开始裁剪。支持设置为 2 位小数，单位：秒。 |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing trim-audio \
--audio-url <audio_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `audio_url` | string | 否 | Local | 输出音频文件路径或 URL |
| `duration` | number | 否 | Local | 音频时长，单位：秒 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing trim-audio --help
mediakit-cli --local editing trim-audio --schema
```
reference/trim-video.md›
# 视频裁剪
## 能力用途
用于视频裁剪，可按指定的开始和结束时间从输入视频截取片段。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud editing trim-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `end_time` | `--end-time` | number | 否 | - | 最小值: 0 | 裁剪结束时间，单位为秒；支持最多两位小数；必须大于 start_time。未传时默认裁剪到输入视频末尾。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `start_time` | `--start-time` | number | 否 | 0 | 最小值: 0 | 裁剪开始时间，单位为秒；支持最多两位小数；必须小于 end_time。默认为 0，表示从视频开头开始。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待裁剪视频的 URL；支持公网 HTTP/HTTPS、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种来源协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；最高支持 4K（3840×2160）分辨率；建议单个输入文件不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud editing trim-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的时长，单位为秒。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率。 |
| `result.video_url` | string | 否 | Cloud 终态 | 裁剪后视频文件地址，文件格式为 MP4。未设置 media_output_destination 时，返回有效期 24 小时的 HTTPS 临时下载链接，需要及时下载保存；设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud editing trim-video --help
mediakit-cli --cloud editing trim-video --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local editing trim-video`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `end_time` | `--end-time` | number | 否 | - | - | 裁剪结束时间，默认为片源结尾。支持设置为 2 位小数，单位：秒。 |
| `start_time` | `--start-time` | number | 否 | 0 | - | 裁剪开始时间，默认为 0， 表示从头开始裁剪。支持设置为 2 位小数，单位：秒。 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频。String 类型，支持http://xxx或https://xxx格式 URL |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local editing trim-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `resolution` | string | 否 | Local | 视频分辨率档位（如 360p, 480p, 720p, 1080p, 2k, 4k） |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local editing trim-video --help
mediakit-cli --local editing trim-video --schema
```
SKILL.md›
---
name: byted-mediakit-editing
version: "0.2.1"
license: "MIT"
description: "面向音频、视频或图片素材组成成片的编辑制作目标，适用于时间线裁剪与拼接、速度和音量调整、视频滤镜、运镜特效、转场、画面裁切旋转翻转、画面叠加、字幕压制、动图截取、淡入淡出、音视频提取与合流、音频混合、文字滚屏成片、图转视频以及多画面空间组合等操作。若用户要给视频添加滤镜效果，或对象和目标族已明确是对现有素材做剪辑、合成、叠加、混合或成片编排，但具体做法不确定，可先加载本 Skill 探索。"
permissions:
- shell
metadata:
requires:
bins: ["mediakit-cli"]
cliHelp: "mediakit-cli editing --help"
product: mediakit-cli/skills
domain: editing
capability_count: 23
---
# editing MediaKit Skill
## 使用规则
1. 先读取 `../byted-mediakit-shared/SKILL.md`，执行统一前置检查；该 Skill 缺失时停止并提示安装。
2. 只从下表选择 `editing` 域工具；相似能力按各工具“能力描述”和参数边界区分。
3. 执行前按需读取对应 reference；参数与结果说明来自同一份已审核文案，完整机器合同以当前 CLI `--schema` 为准。
4. 缺少必填参数、鉴权环境变量或真实输入资源时，向用户索取；通用可选字段只能透传用户明确提供的值，其他可选字段可由明确意图准确确定，但不得伪造。
5. 执行时设置 `MEDIAKIT_SURFACE=skill`，指定调用来源是 Skill。
6. 执行时把 `MEDIAKIT_RUNTIME` 设置为当前 Agent 宿主，避免 CLI 无法可靠识别父级 Agent。
## 澄清与跨域路由
若只给出媒体类型而未说明要剪、合、叠、调、加滤镜还是分析，应先澄清。纯图像增强、抠图、OCR、图片水印或图片尺寸优化应路由到 image；视频画质增强、内容理解、从视频提取字幕、语音转字幕、字幕擦除、暗水印、人像或绿幕抠像等视频智能处理应路由到 video；音频转码、语音端点检测、人声背景分离等非剪辑目标应路由到 audio。滤镜效果包括春日/晚霞/鲜亮/白皙/食物等，具体参数以工具 reference 为准。
## 工具列表
| 工具 | 说明 | 支持模式 | 命令 | 参考 |
| --- | --- | --- | --- | --- |
| add-image-to-video | 支持将指定图片（如 Logo、水印等）叠加到视频画面上。 | Cloud / Local | `mediakit-cli editing add-image-to-video` | [reference/add-image-to-video.md](reference/add-image-to-video.md) |
| add-subtitle-to-video | 将字幕文件或文本内容按自定义样式压制到视频画面中，生成带内嵌字幕的新视频。 | Cloud / Local | `mediakit-cli editing add-subtitle-to-video` | [reference/add-subtitle-to-video.md](reference/add-subtitle-to-video.md) |
| adjust-audio-speed | 用于音频调速，可调整音频播放倍速，实现快放或慢放效果。 | Cloud / Local | `mediakit-cli editing adjust-audio-speed` | [reference/adjust-audio-speed.md](reference/adjust-audio-speed.md) |
| adjust-video-speed | 用于视频调速，通过调整播放倍速产生快放或慢放效果。 | Cloud / Local | `mediakit-cli editing adjust-video-speed` | [reference/adjust-video-speed.md](reference/adjust-video-speed.md) |
| adjust-video-volume | 用于调整输入视频的音量大小，也可实现静音。 | Cloud / Local | `mediakit-cli editing adjust-video-volume` | [reference/adjust-video-volume.md](reference/adjust-video-volume.md) |
| apply-camera-motion | 对输入视频在指定时间段内添加一种运镜特效，常用于素材二次创作、营销片头、短剧动效等场景。 | Cloud | `mediakit-cli editing apply-camera-motion` | [reference/apply-camera-motion.md](reference/apply-camera-motion.md) |
| apply-video-filter | 为指定视频添加滤镜效果。 | Cloud | `mediakit-cli editing apply-video-filter` | [reference/apply-video-filter.md](reference/apply-video-filter.md) |
| concat-audio | 拼接多个音频片段。 | Cloud / Local | `mediakit-cli editing concat-audio` | [reference/concat-audio.md](reference/concat-audio.md) |
| concat-video | 将多个视频按顺序拼接成一个完整的视频文件，并支持在拼接处添加转场效果。 | Cloud / Local | `mediakit-cli editing concat-video` | [reference/concat-video.md](reference/concat-video.md) |
| crop-video | 按指定的矩形区域裁剪视频画面，裁剪结果仅保留指定的需要区域。 | Cloud | `mediakit-cli editing crop-video` | [reference/crop-video.md](reference/crop-video.md) |
| extract-animated-image | 从视频中按指定开始时间和结束时间截取一段画面，生成 GIF 或 WebP 动图，常用于制作封面动图、营销素材和短预览。 | Cloud | `mediakit-cli editing extract-animated-image` | [reference/extract-animated-image.md](reference/extract-animated-image.md) |
| extract-audio | 从输入视频文件中分离音轨，生成独立的音频文件。 | Cloud / Local | `mediakit-cli editing extract-audio` | [reference/extract-audio.md](reference/extract-audio.md) |
| fade-audio | 对输入音频的起止位置实现淡入或淡出效果，输出处理后的音频文件。 | Cloud / Local | `mediakit-cli editing fade-audio` | [reference/fade-audio.md](reference/fade-audio.md) |
| fade-video-audio | 在片头或片尾对输入视频音轨执行淡入或淡出处理，用于弱化音轨突兀的起止，提升成片听感。输出处理后的视频文件。 | Cloud / Local | `mediakit-cli editing fade-video-audio` | [reference/fade-video-audio.md](reference/fade-video-audio.md) |
| flip-video | 用于视频画面翻转，对指定视频进行上下或左右镜像翻转。 | Cloud / Local | `mediakit-cli editing flip-video` | [reference/flip-video.md](reference/flip-video.md) |
| image-to-video | 将多张图片按顺序组合成动态视频，可配置转场动画和镜头内动画；仅把现有图片做成带动效的视频，不支持根据参考图生成新的画面内容。 | Cloud | `mediakit-cli editing image-to-video` | [reference/image-to-video.md](reference/image-to-video.md) |
| mix-audio | 将多个音频文件（如背景音乐、音效、人声）进行混音，生成一个新的音频文件。<br>处理耗时：处理耗时与视频时长正相关。视频时长越长，处理耗时越长。平均 RTF（处理耗时/原片时长）为 1。<br>输出音频的时长以最长的音频为准。<br>输出视频格式：mp3 | Cloud / Local | `mediakit-cli editing mix-audio` | [reference/mix-audio.md](reference/mix-audio.md) |
| mux-audio-video | 可将输入的音频流与视频流合并成一个新的视频文件，并可选择保留或替换视频的原有音轨；当音视频时长不一致时，可进行对齐处理。 | Cloud / Local | `mediakit-cli editing mux-audio-video` | [reference/mux-audio-video.md](reference/mux-audio-video.md) |
| rotate-video | 用于视频画面旋转，对指定视频进行整体旋转。 | Cloud | `mediakit-cli editing rotate-video` | [reference/rotate-video.md](reference/rotate-video.md) |
| stitch-video | 将多个视频在空间上按水平或垂直方向拼接成一个完整画面，适用于多视角对比、画面组合等场景。 | Cloud | `mediakit-cli editing stitch-video` | [reference/stitch-video.md](reference/stitch-video.md) |
| text-to-scrolling-video | 将指定文本内容转换为文字滚屏视频，输出视频为固定 9:16 竖版，常用于小说推文、内容讲解和歌词视频等场景。 | Cloud | `mediakit-cli editing text-to-scrolling-video` | [reference/text-to-scrolling-video.md](reference/text-to-scrolling-video.md) |
| trim-audio | 用于音频裁剪，按指定的开始时间和结束时间从输入音频中截取片段。 | Cloud / Local | `mediakit-cli editing trim-audio` | [reference/trim-audio.md](reference/trim-audio.md) |
| trim-video | 用于视频裁剪，可按指定的开始和结束时间从输入视频截取片段。 | Cloud / Local | `mediakit-cli editing trim-video` | [reference/trim-video.md](reference/trim-video.md) |