volcengine/mediakit-cli검사 통과
SKILL DETAIL
byted-mediakit-video
volcengine/mediakit-cli/byted-mediakit-video
面向视频文件的智能处理、媒资理解、画质治理与画质检测、抽帧、隐私保护、语音转字幕、字幕提取、字幕擦除、水印处理、精彩片段与高光拆条分析生成、剧情结构化与剧本整理、场景与语义分段、画面文字识别、视频转码转封装及抠像换脸等目标。若对象和目标族已明确属于视频增强、视频分析理解、视频内容结构化、从视频提取字幕、语音转字幕、视频字幕识别或擦除、视频隐私脱敏、视频媒资探测或分发适配，但具体能力不确定，可先加载本 Skill 探索。
설치 수 · 324출처 보기
Installation
npx skills add https://github.com/volcengine/mediakit-cli --skill byted-mediakit-video
스킬 파일
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-video-invisible-watermark.md›
# 添加视频暗水印
## 能力用途
用于视频暗水印添加。在不影响视频画面视觉质量与完整性的前提下，将一串数字信息隐藏式地嵌入视频文件中。适用于视频版权保护、内容泄露溯源、文件真实性校验等场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video add-video-invisible-watermark`
- 生命周期：异步
- 返回方式：返回 `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。支持 mp4、mov、mkv、flv、ts、avi、wmv 等主流视频格式；支持公网 HTTP/HTTPS URL、本地文件路径、视频点播 vod://、对象存储 tos:// 四种输入协议；分辨率最高支持 4K。 |
| `watermark_content` | `--watermark-content` | string | 是 | - | 格式: "^[1-9][0-9]{0,18}$" | 待嵌入视频的隐藏数字信息，用于版权追溯。需传入一个代表 64 位正整数的字符串，且必须为纯数字字符串；数字必须在 1 至 9223372036854775807 之间；不允许使用前导零或包含任何非数字字符。 |
| `watermark_level` | `--watermark-level` | string | 否 | "normal" | 枚举: ["low","normal","high"] | 可选的暗水印强度，用于决定抗攻击性与画面影响程度的平衡。normal 为标准强度，在画质与抗攻击性之间取得平衡，适用于大多数场景；high 为高强度，抗攻击性最强，能抵抗更强的视频处理，但对画面的潜在影响也相对更大；默认值为 normal 标准强度。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video add-video-invisible-watermark \
--video-url <video_url> \
--watermark-content <watermark_content>
```
仅使用用户真实输入替换占位符；可选 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 终态 | 已嵌入暗水印的视频文件地址。设置 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 video add-video-invisible-watermark --help
mediakit-cli video add-video-invisible-watermark --schema
```
reference/analyze-video-highlights.md›
# 高光片段提取
## 能力用途
支持短剧 Miniseries 和小游戏 Game 两种分析模型，用于高光片段提取，并输出精准时间戳、高光打分、OCR 文本和画面描述，供二次开发或内容分析。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video analyze-video-highlights`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--video-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--minigame-info`）需传合法 JSON 字符串并整体加单引号，例如 `--minigame-info '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video analyze-video-highlights \
--video-urls "url1,url2"
--model <model> \
--mode <mode>
```
仅使用用户真实输入替换占位符；可选 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 可打印字符。 默认不传。用户明确指定时原样使用；用户明确要求重试时，同一逻辑请求的重试链必须复用同一 token。已有 token 时必须复用原值；此前请求未带 token 时，可从本次重试开始创建一次并持续复用，但该 token 不对此前请求提供追溯幂等。业务参数变化视为新请求，不得复用旧 token。不得为每次尝试生成不同值。CLI/MCP runtime 不判断重试意图，也不自动生成 token。 |
| `minigame_info` | `--minigame-info` | object | 否 | - | - | 仅当 model 为 Game 时可选填，用于提供小游戏描述信息以辅助模型更精准地识别高光内容。 |
| `minigame_info.highlight_definition` | - | string | 否 | - | 最长长度: 5000 | 描述游戏中的高光时刻或精彩瞬间的定义。 |
| `minigame_info.name` | - | string | 否 | - | 最长长度: 5000 | 用于标识游戏内容的游戏名称。 |
| `minigame_info.play_definition` | - | string | 否 | - | 最长长度: 5000 | 描述游戏的玩法规则或核心特点。 |
| `mode` | `--mode` | string | 是 | - | 枚举: ["StorylineCuts","HighlightExtract"] | 当 model 为 Miniseries 时，mode 必须为 StorylineCuts；当 model 为 Game 时，mode 必须为 HighlightExtract。 |
| `model` | `--model` | string | 是 | - | 枚举: ["Miniseries","Game"] | Miniseries 是短剧模型，结合故事线理解，智能识别钩子点、反转、亲密、冲突等高光片段；Game 是小游戏模型，精准识别玩法操作片段和击杀、连胜、满血反杀等高光瞬间。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID；不传时默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以按队列对应的项目进行分账。队列可创建和管理，系统会自动分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 100 | 待分析的视频 URL 列表，不同模型对输入视频的数量、时长和内容有不同要求。支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；输入分辨率最高支持 1080p。用于短剧高光片段提取时，单次任务最多支持输入 30 个视频文件，累计总时长建议不超过 45 分钟，输入素材必须同时包含视频流和音频流，视频画面下半部分垂直位置 0.5-1.0 范围内必须包含清晰居中的中文字幕，音频轨道必须包含清晰可识别的中文对话文本；仅含 BGM（含歌词）、纯音乐、语气词或无有效语义的声音将无法准确识别剧情逻辑。用于小游戏高光片段提取时，当前单次任务仅支持输入单个视频文件；输入多个视频时默认选择第一个文件分析，输入文件时长不得超过 10 分钟。 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
### 任务结果查询
提交成功后会返回 `task_id`，再执行 `mediakit-cli shared query-task --task-id <task_id>` 查询。
- 当前命令：`mediakit-cli video analyze-video-highlights`
- 推荐查询：`mediakit-cli shared query-task --task-id <task_id>`
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video analyze-video-highlights --help
mediakit-cli video analyze-video-highlights --schema
```
reference/analyze-video-storyline.md›
# 剧情故事线分析
## 能力用途
用于剧情故事线分析，基于大模型视频理解分析单个或多个长视频并生成结构化剧情数据。分析结果包含两部分：按时间顺序排列的剧情片段，以及基于视频片段整理和归纳出的高光故事线。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video analyze-video-storyline`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-snapshot`）只能写成 `--enable-snapshot=true` 或 `--enable-snapshot=false`，也可用裸 `--enable-snapshot`（等价 true）；禁止空格传值 `--enable-snapshot true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
- 数组参数（`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--video-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video analyze-video-storyline \
--video-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 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 生成、推断或补写。 |
| `enable_snapshot` | `--enable-snapshot` | boolean | 否 | false | - | enable_snapshot 可选，用于控制是否为每个剧情片段生成关键帧快照；默认 false。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 30 | video_urls 是待处理的视频 URL 列表，支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 和 tos:// 四种协议来源，支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；单次任务最多支持传入 30 个视频文件；输入视频分辨率最高支持 1080p；输入视频累计总时长不得超过 210 分钟，即 3.5 小时；建议单个视频文件时长不得超过 150 分钟，即 2.5 小时。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | duration 表示输入视频的总时长，单位为秒。 |
| `result.source_video_info` | array<object> | 否 | Cloud 终态 | source_video_info 是输入源视频的分析结果列表，包含原始 URL、AI 生成的标题和简介等信息；支持通过 storyline_clips 标注的源视频索引追溯每个片段对应的输入文件。 |
| `result.source_video_info[].source_video_index` | integer | 否 | Cloud 终态 | source_video_index 是从 0 开始的片源索引。 |
| `result.source_video_info[].source_video_summary` | string | 否 | Cloud 终态 | source_video_summary 是视频简介。 |
| `result.source_video_info[].source_video_tag` | array<string> | 否 | Cloud 终态 | source_video_tag 是视频标签列表。 |
| `result.source_video_info[].source_video_title` | string | 否 | Cloud 终态 | source_video_title 是视频标题。 |
| `result.source_video_info[].source_video_url` | string | 否 | Cloud 终态 | source_video_url 是片源的原始 URL。 |
| `result.storyline_clips` | array<object> | 否 | Cloud 终态 | storyline_clips 是 AI 将一个或多个长视频的故事按剧情发展智能切分并按时间顺序排列得到的基础视频片段数组；storyline_clips 是最基础、最详细的分析结果，每个片段包含标题、简介、源视频起止时间和精彩度评分。 |
| `result.storyline_clips[].clip_dialogue` | string | 否 | Cloud 终态 | clip_dialogue 是视频片段内的主要对话文本。 |
| `result.storyline_clips[].clip_end_time` | number | 否 | Cloud 终态 | clip_end_time 是视频片段在源视频中的结束时间，单位为秒。 |
| `result.storyline_clips[].clip_index` | integer | 否 | Cloud 终态 | clip_index 是从 0 开始的视频片段唯一索引。 |
| `result.storyline_clips[].clip_score` | number | 否 | Cloud 终态 | clip_score 是高光打分，分数越高表示越精彩；范围必须为 1 到 5。 |
| `result.storyline_clips[].clip_snapshot_url` | string | 否 | Cloud 终态 | clip_snapshot_url 是关键帧快照 URL，仅在请求中 enable_snapshot 为 true 时返回；enable_snapshot 开启后，storyline_clips 的每个对象包含 clip_snapshot_url。 |
| `result.storyline_clips[].clip_start_time` | number | 否 | Cloud 终态 | clip_start_time 是视频片段在源视频中的开始时间，单位为秒。 |
| `result.storyline_clips[].clip_summary` | string | 否 | Cloud 终态 | clip_summary 是视频片段简介。 |
| `result.storyline_clips[].clip_title` | string | 否 | Cloud 终态 | clip_title 是视频片段标题。 |
| `result.storyline_clips[].source_video_index` | integer | 否 | Cloud 终态 | source_video_index 标识视频片段来自哪个输入视频，并对应 source_video_info 的片源索引。 |
| `result.storyline_highlights` | array<object> | 否 | Cloud 终态 | storyline_highlights 是基于 storyline_clips 整理和归纳出的故事线数组。 |
| `result.storyline_highlights[].highlight_clips_index` | array<integer> | 否 | Cloud 终态 | highlight_clips_index 是组成该高光故事线的剧情片段索引列表，对应 storyline_clips 中的 clip_index；highlight_clips_index 列表说明一条故事线由哪些剧情片段组成。 |
| `result.storyline_highlights[].highlight_index` | integer | 否 | Cloud 终态 | highlight_index 是从 0 开始的高光故事线唯一索引。 |
| `result.storyline_highlights[].highlight_summary` | string | 否 | Cloud 终态 | highlight_summary 是高光故事线简介。 |
| `result.storyline_highlights[].highlight_title` | string | 否 | Cloud 终态 | highlight_title 是高光故事线标题。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video analyze-video-storyline --help
mediakit-cli video analyze-video-storyline --schema
```
reference/asr-subtitles.md›
# 语音转字幕（ASR)
## 能力用途
从视频或音频的语音中识别并提取带时间戳的字幕文本；适用于提取视频字幕、语音转字幕、听写对白等诉求。识别对象是音轨中的语音内容，不是画面上已烧录的硬字幕。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video asr-subtitles`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-confidence`、`--enable-speaker-info`）只能写成 `--enable-confidence=true` 或 `--enable-confidence=false`，也可用裸 `--enable-confidence`（等价 true）；禁止空格传值 `--enable-confidence true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video asr-subtitles
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio_url` | `--audio-url` | string | 否 | - | - | audio_url 是待处理的音频 URL；支持 mp3、m4a、wav 等主流音频格式；音频文件时长必须不超过 3 小时；支持公网 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 生成、推断或补写。 |
| `content_type` | `--content-type` | string | 否 | - | 枚举: ["speech","singing"] | content_type 指定识别内容类型；支持 speech 表示普通说话，singing 表示唱歌；content_type 留空时由算法自动探测识别内容类型。 |
| `enable_confidence` | `--enable-confidence` | boolean | 否 | false | - | enable_confidence 控制是否返回每个字幕片段的置信度，默认为 false；开启 enable_confidence 后，结果中包含 confidence 字段。 |
| `enable_speaker_info` | `--enable-speaker-info` | boolean | 否 | false | - | enable_speaker_info 控制是否开启说话人识别，默认为 false；开启 enable_speaker_info 后，结果中包含 speaker 字段。 |
| `language` | `--language` | string | 否 | - | 枚举: ["cmn-Hans-CN","eng-US"] | language 指定识别语种；支持 cmn-Hans-CN 表示简体中文，eng-US 表示英语；language 留空时由算法自动探测语种。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 否 | - | - | video_url 是待处理的视频 URL；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；视频文件时长必须不超过 3 小时；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；video_url 和 audio_url 同时存在时优先使用 video_url。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | duration 是输入音频或视频的总时长，单位为秒。 |
| `result.subtitles` | array<object> | 否 | Cloud 终态 | subtitles 是字幕片段列表，每个元素包含字幕文本和时间戳。 |
| `result.subtitles[].confidence` | number | 否 | Cloud 终态 | confidence 是字幕片段的置信度得分，必须不小于 0 且不大于 1，仅在请求中的 enable_confidence 为 true 时返回。 |
| `result.subtitles[].end_time` | number | 否 | Cloud 终态 | end_time 是字幕片段的结束时间，单位为秒。 |
| `result.subtitles[].speaker` | string | 否 | Cloud 终态 | speaker 是说话人标识，仅在请求中的 enable_speaker_info 为 true 时返回。 |
| `result.subtitles[].start_time` | number | 否 | Cloud 终态 | start_time 是字幕片段的起始时间，单位为秒。 |
| `result.subtitles[].subtitle_text` | string | 否 | Cloud 终态 | subtitle_text 是识别出的字幕文本。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video asr-subtitles --help
mediakit-cli video asr-subtitles --schema
```
reference/assess-video-quality.md›
# 视频画质检测（VQScore）
## 能力用途
用于视频画质检测。
## 参数填写规则
- 公网可访问的视频 Url，异步获取该视频的 VQScore 画质评分。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video assess-video-quality`
- 生命周期：异步
- 返回方式：返回 `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 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 用于指定待检测的视频 URL，支持公网 HTTP/HTTPS URL、本地上传、火山引擎视频点播和火山引擎对象存储四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；输入视频最高支持 4K (3840×2160) 分辨率。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video assess-video-quality \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输入视频时长，单位为秒。 |
| `result.vq_score` | number | 否 | Cloud 终态 | VQScore 画质评分范围 [0,100]，分数越高画质越好；[0, 60) 表示主观感受较差，[60, 70) 表示主观感受良好，[70, 100] 表示主观感受清晰。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video assess-video-quality --help
mediakit-cli video assess-video-quality --schema
```
reference/drama-recap-vertical.md›
# 解说视频生成（短剧行业模型）
## 能力用途
基于输入短剧剧集的角色与剧情故事线理解，自动提取高光片段并生成全新解说视频；支持文字解说（原片高光混剪 + 屏幕文字）与旁白解说（原片高光混剪 + AI 语音 + BGM），并可套用短剧三要素视觉模板。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video drama-recap-vertical`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-return-poster`）只能写成 `--enable-return-poster=true` 或 `--enable-return-poster=false`，也可用裸 `--enable-return-poster`（等价 true）；禁止空格传值 `--enable-return-poster true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
- 数组参数（`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--video-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--edit-param`、`--narrate-options`、`--text-options`）需传合法 JSON 字符串并整体加单引号，例如 `--edit-param '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video drama-recap-vertical \
--video-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 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 生成、推断或补写。 |
| `edit_param` | `--edit-param` | object | 否 | - | - | 支持在 narrate 和 text 两种模式中使用；可选配置成片剪辑效果，包括套用包含剧名、角标和提示语的短剧三要素视觉模板。 |
| `edit_param.mode` | - | string | 是 | "BasicEdit" | 枚举: ["BasicEdit","TemplateEdit"] | 默认为 BasicEdit；支持 BasicEdit 和 TemplateEdit，BasicEdit 仅拼接高光片段，TemplateEdit 在基础剪辑上套用短剧三要素视觉模板。 |
| `edit_param.template_edit` | - | object | 否 | - | - | 仅当 edit_param.mode 为 TemplateEdit 时生效。 |
| `edit_param.template_edit.hint` | - | string | 否 | - | 最长长度: 20 | 画面左右两侧的一行短剧提示语，可选用于概括核心冲突或亮点，也可用作免责声明；不得超过 20 个字。 |
| `edit_param.template_edit.template` | - | string | 否 | "热门短剧1" | 枚举: ["热门短剧1","热门短剧2","热门短剧3","热门短剧4","热门短剧5"] | 默认为 热门短剧1；决定剧名、角标和提示语的位置及样式；支持 热门短剧1、热门短剧2、热门短剧3、热门短剧4、热门短剧5。 |
| `edit_param.template_edit.title` | - | string | 否 | - | 最长长度: 22 | 展示在解说视频画面上的短剧名称，用于品牌识别和引导用户搜索；不得超过 22 个字。 |
| `enable_return_poster` | `--enable-return-poster` | boolean | 否 | false | - | 默认为 false；true 会在任务结果中返回 poster_url，false 不返回封面图。 |
| `max_count` | `--max-count` | integer | 否 | 3 | 最小值: 1；最大值: 100 | 单次任务期望生成的解说视频数量上限，最小值为 1，不得超过 100，默认为 3。 |
| `max_duration` | `--max-duration` | number | 否 | 180 | 最小值: 1；最大值: 7200 | 每个解说视频的时长上限，单位为秒，最小值为 1，最大值为 7200，默认为 180 秒。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `min_duration` | `--min-duration` | number | 否 | 30 | 最小值: 1；最大值: 7200 | 每个解说视频的时长下限，单位为秒，最小值为 1，最大值为 7200，默认为 30 秒。 |
| `mode` | `--mode` | string | 否 | "text" | 枚举: ["narrate","text"] | 默认为 text；支持 narrate 和 text 两种模式。narrate 生成原片高光混剪、AI 语音解说和 BGM；text 生成原片高光混剪与屏幕文字解说。 |
| `narrate_bgm_url` | `--narrate-bgm-url` | string | 否 | - | - | 指定旁白解说模式下使用的背景音乐音频 URL；仅支持公网可访问的 HTTP/HTTPS URL；支持 mp3、m4a、wav 等主流音频格式；可选，不传时生成的解说视频不添加背景音乐。 |
| `narrate_options` | `--narrate-options` | object | 否 | - | - | 仅当 mode 为 narrate 时生效。 |
| `narrate_options.enable_narrate_bgm` | - | boolean | 否 | true | - | 默认为 true；true 启用 BGM 并使用 narrate_bgm_url 指定的音频，false 关闭背景音乐。 |
| `narrate_options.erase_subtitle_mode` | - | string | 否 | "mosaic" | 枚举: ["mosaic","standard"] | 默认为 mosaic；支持 mosaic 和 standard。mosaic 直接高斯模糊遮盖字幕区域，处理效率最高，适合快速遮挡且画面完整性要求不高的场景；standard 平衡擦除效果与效率，对纯色或简单背景效果良好，但复杂纹理或剧烈运动背景可能残留轻微涂抹痕迹。 |
| `narrate_options.narrate_ratio` | - | number | 否 | 0.3 | 最小值: 0；最大值: 1 | 控制旁白解说时长占生成视频时长的比例，最小值为 0，最大值为 1，默认为 0.3，建议不超过 0.5。 |
| `opening_hook` | `--opening-hook` | string | 否 | "auto" | 枚举: ["auto","force","disable"] | 精彩片段前置策略默认为 auto；支持 auto、force 和 disable。auto 会智能判断是否将最精彩片段前置到视频开头，force 强制开启精彩前置，disable 关闭精彩前置。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `text_options` | `--text-options` | object | 否 | - | - | 仅当 mode 为 text 时生效。 |
| `text_options.align_type` | - | string | 否 | "left" | 枚举: ["left","middle","right"] | 默认为 left；支持 left、middle、right，分别表示左对齐、居中对齐和右对齐。 |
| `text_options.border_color` | - | string | 否 | "#00000080" | 格式: "^#[0-9A-Fa-f]{8}$" | 花字描边颜色必须使用 #RRGGBBAA 格式，默认为 #00000080。 |
| `text_options.border_width` | - | integer | 否 | 2 | 最小值: 1 | 花字描边宽度单位为 px，默认为 2，建议不超过字号的 0.1 倍。 |
| `text_options.font_color` | - | string | 否 | "#FFFFF290" | 格式: "^#[0-9A-Fa-f]{8}$" | 花字颜色必须使用 #RRGGBBAA 格式，默认为 #FFFFF290。 |
| `text_options.font_size` | - | integer | 否 | - | 最小值: 1 | 花字字号单位为 px；未传时按视频短边除以 24 自动计算，例如 720p 默认 30、1080p 默认 45；不得小于 1。 |
| `text_options.font_type` | - | string | 否 | "SY_Bold" | 枚举: ["SY_Bold","SY_Black"] | 默认为 SY_Bold；支持 SY_Bold 和 SY_Black，分别表示思源粗体和思源黑体。 |
| `text_options.inner_padding` | - | integer | 否 | 1 | 最小值: 0 | 花字内边距单位为 px，默认为 1。 |
| `text_options.is_bold` | - | boolean | 否 | false | - | 花字是否加粗，默认为 false。 |
| `text_options.is_italic` | - | boolean | 否 | true | - | 花字是否斜体，默认为 true。 |
| `text_options.is_underline` | - | boolean | 否 | false | - | 花字是否添加下划线，默认为 false。 |
| `text_options.shadow_color` | - | string | 否 | "#00000080" | 格式: "^#[0-9A-Fa-f]{8}$" | 花字阴影颜色必须使用 #RRGGBBAA 格式，默认为 #00000080。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 30 | 待处理短剧原片的视频源 URL 列表；支持公网 HTTP/HTTPS、本地文件路径、视频点播 vod:// 和对象存储 tos:// 四类协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；单次任务支持传入 1 到 30 个视频文件；累计时长不得超过 120 分钟，即 2 小时；输入分辨率当前仅支持 1080p；输入素材需保持分辨率一致，否则会有兼容性问题；每个输入视频必须同时包含视频流和音频流；音频轨道必须包含清晰可识别的中文对话文本，仅含 BGM、纯音乐或语气词无法准确还原剧情；建议视频画面下半部分包含清晰居中的中文字幕，以提升文字解说定位和剧情理解准确度。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.input_duration` | number | 否 | Cloud 终态 | 输入视频总时长，单位为秒。 |
| `result.mode` | string | 否 | Cloud 终态 | 解说视频模式。 |
| `result.output_duration` | number / null | 否 | Cloud 终态 | 所有输出解说视频的总时长，单位为秒。 |
| `result.video_infos` | array<object> | 否 | Cloud 终态 | 每个解说视频的详细信息列表，并与 video_urls 顺序一致。 |
| `result.video_infos[].duration` | number / null | 否 | Cloud 终态 | 该条解说视频的时长，单位为秒。 |
| `result.video_infos[].poster_url` | string | 否 | Cloud 终态 | 未生成封面图或 enable_return_poster 为 false 时，poster_url 为空字符串。 |
| `result.video_infos[].size` | integer / string / null | 否 | Cloud 终态 | 该条解说视频的文件大小，单位为字节。 |
| `result.video_infos[].video_url` | string | 否 | Cloud 终态 | 设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址；未设置 media_output_destination 时，返回有效期 24 小时的 HTTPS 临时下载链接。 |
| `result.video_urls` | array<string> | 否 | Cloud 终态 | 设置 media_output_destination 后，video_urls 返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址；未设置 media_output_destination 时，video_urls 返回有效期 24 小时的 HTTPS 临时下载链接。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video drama-recap-vertical --help
mediakit-cli video drama-recap-vertical --schema
```
reference/drama-recap.md›
# 解说视频生成
## 能力用途
基于已完成的剧本还原任务，可使用自定义解说词或由 AI 自动生成解说词，生成带 AI 配音与解说字幕的营销或解说视频；可配置音色、字幕样式与原文字幕擦除。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video drama-recap`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- `--drama-script-task-id` 必须来自已完成的剧本还原终态结果。若用户未提供：先调用 [drama-script.md](drama-script.md)，轮询至终态后读取 `result.drama_script_task_id`，再调用本工具；禁止猜测或伪造。
- 布尔参数（`--erase-subtitle`）只能写成 `--erase-subtitle=true` 或 `--erase-subtitle=false`，也可用裸 `--erase-subtitle`（等价 true）；禁止空格传值 `--erase-subtitle true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
- 对象或对象数组参数（`--drama-recap-config`、`--miniseries-edit`、`--speaker-config`、`--subtitle-config`）需传合法 JSON 字符串并整体加单引号，例如 `--drama-recap-config '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video drama-recap \
--drama-script-task-id <drama_script_task_id>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `batch_count` | `--batch-count` | integer | 否 | 1 | 最小值: 1；最大值: 100 | 批量生成解说视频数量。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `drama_recap_config` | `--drama-recap-config` | object | 否 | - | - | 解说文案与生成策略配置对象。 |
| `drama_recap_config.auto_generate_recap` | - | boolean | 否 | false | - | 是否由 AI 自动生成解说词。true 时不能设置 recap_text。 |
| `drama_recap_config.enable_repeat_match` | - | boolean | 否 | false | - | 是否允许解说词匹配重复的视频画面。 |
| `drama_recap_config.pause_time` | - | integer | 否 | 120 | 最小值: 1；最大值: 1000 | AI 配音句间停顿时长（毫秒），取值范围 [1, 1000]。 |
| `drama_recap_config.prefer_speed` | - | boolean | 否 | false | - | 是否优先生成速度。 |
| `drama_recap_config.style` | - | string | 否 | - | 最长长度: 500 | AI 生成解说词的风格指令，如悬疑、搞笑、轻松等。仅 auto_generate_recap=true 时有效。 |
| `drama_recap_config.text_length` | - | integer | 否 | - | 最小值: 1；最大值: 5000 | AI 生成解说词的期望长度（UTF-8 字符数），仅 auto_generate_recap=true 时有效。 |
| `drama_recap_config.text_speed` | - | number | 否 | 1 | 最小值: 0.5；最大值: 2 | 解说词语速，取值范围 [0.5, 2.0]。 |
| `drama_script_task_id` | `--drama-script-task-id` | string | 是 | - | 最短长度: 1 | 已成功完成的剧本还原任务的 task_id（对应剧本还原终态结果 `result.drama_script_task_id`）。用户未提供时：先按 [drama-script.md](drama-script.md) 提交并完成剧本还原，再取终态 `result.drama_script_task_id` 填入本参数；不得编造、猜测或使用未完成任务的 ID。 |
| `erase_mode` | `--erase-mode` | string | 否 | "standard" | 枚举: ["standard"] | 字幕擦除模式。仅 erase_subtitle=true 时生效；当前仅支持 standard。 |
| `erase_subtitle` | `--erase-subtitle` | boolean | 否 | false | - | 是否擦除原视频中的字幕。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `miniseries_edit` | `--miniseries-edit` | object | 否 | - | - | 短剧三要素视觉模板配置对象。仅适用于竖屏短剧。 |
| `miniseries_edit.hint` | - | string | 否 | - | 最长长度: 20 | 短剧提示语，不超过 20 个字。 |
| `miniseries_edit.template` | - | string | 否 | - | 枚举: ["热门短剧1","热门短剧2","热门短剧3","热门短剧4","热门短剧5"] | 短剧三要素视觉模板名称。 |
| `miniseries_edit.title` | - | string | 否 | - | 最长长度: 15 | 短剧名称，不超过 15 个字。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `recap_text` | `--recap-text` | string | 否 | - | 最长长度: 5000 | 自定义解说词文本。当 drama_recap_config.auto_generate_recap=false（默认）时必填；为 true 时不可设置。 |
| `speaker_config` | `--speaker-config` | object | 否 | - | - | 配音配置对象。推荐使用该对象组织音色相关参数；未传时按默认音色处理。 |
| `speaker_config.voice_type` | - | string | 否 | "Yunxi" | 枚举: ["Yunxi","Yunjian","Yunfeng","Yunyi","Yunjie","Yunze","Yunye","Xiaoxiao","Xiaochen","Xiaohan","Xiaomo"] | 音色名称。预置音色：Yunxi / Yunjian / Yunfeng / Yunyi / Yunjie / Yunze / Yunye / Xiaoxiao / Xiaochen / Xiaohan / Xiaomo。 |
| `subtitle_config` | `--subtitle-config` | object | 否 | - | - | 字幕样式配置对象。可按需只传部分字段，未传字段按默认行为处理。 |
| `subtitle_config.align_type` | - | integer | 否 | 1 | - | 文本对齐方式。横排：0=左对齐，1=居中，2=右对齐；竖排：1=居中，3=上对齐，4=下对齐。 |
| `subtitle_config.alpha` | - | number | 否 | 1 | 最小值: 0；最大值: 1 | 字体透明度，取值范围 [0,1]。0 为透明。默认为 1。 |
| `subtitle_config.background_border_size` | - | number | 否 | 0 | 最小值: 0 | 字幕背景边框大小。 |
| `subtitle_config.background_color` | - | string | 否 | "#00000000" | - | 字幕背景颜色，RGBA 格式。 |
| `subtitle_config.border_color` | - | string | 否 | "#00000000" | - | 字幕描边颜色，RGBA 格式。 |
| `subtitle_config.border_width` | - | integer | 否 | - | 最小值: 1 | 字幕描边宽度（pixel）。 |
| `subtitle_config.bottom_right_x` | - | integer | 否 | - | 最小值: 1 | 字幕矩形区域右下角 X 坐标（pixel）。需大于 top_left_x。 |
| `subtitle_config.bottom_right_y` | - | integer | 否 | - | 最小值: 1 | 字幕矩形区域右下角 Y 坐标（pixel）。需大于 top_left_y。 |
| `subtitle_config.disable_subtitle` | - | boolean | 否 | false | - | 是否不在生成的解说视频中添加新字幕。 |
| `subtitle_config.font_color` | - | string | 否 | "#FFFFFFFF" | - | 字幕字体颜色，RGBA 格式（如 "#FFCC66FF"）。 |
| `subtitle_config.font_size` | - | integer | 否 | - | 最小值: 1 | 字幕字体大小（pixel）。 |
| `subtitle_config.font_type` | - | string | 否 | "sy_black" | 枚举: ["sy_black","pm_zhengdao"] | 字幕字体类型。仅支持 sy_black(思源黑体)(阿里巴巴普惠体)、pm_zhengdao(庞门正道标题体)。 |
| `subtitle_config.line_max_width` | - | number | 否 | 1 | 最小值: 0；最大值: 1 | 自动换行宽度占比，取值 [0,1]。 |
| `subtitle_config.top_left_x` | - | integer | 否 | - | 最小值: 0 | 字幕矩形区域左上角 X 坐标（pixel）。 |
| `subtitle_config.top_left_y` | - | integer | 否 | - | 最小值: 0 | 字幕矩形区域左上角 Y 坐标（pixel）。 |
| `subtitle_config.typesetting` | - | integer | 否 | 0 | 枚举: [0,1] | 文字排列方向：0=横排，1=竖排。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number / null | 否 | Cloud 终态 | 输出视频时长（秒）。 |
| `result.error` | object / null | 否 | Cloud 终态 | 错误信息（失败时返回）。 |
| `result.error.code` | string / null | 否 | Cloud 终态 | 失败时返回的错误码。 |
| `result.error.message` | string / null | 否 | Cloud 终态 | 失败时返回的错误信息。 |
| `result.failed_count` | integer / null | 否 | Cloud 终态 | 失败数量。 |
| `result.success_count` | integer / null | 否 | Cloud 终态 | 成功生成数量。 |
| `result.total_count` | integer / null | 否 | Cloud 终态 | 批量生成总数（batch_count>1 时返回）。 |
| `result.video_url` | string / null | 否 | Cloud 终态 | 生成的解说视频 URL（batch_count=1 时返回）。 |
| `result.video_urls` | array<string> | 否 | Cloud 终态 | 生成的解说视频 URL 列表（batch_count>1 时返回）。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video drama-recap --help
mediakit-cli video drama-recap --schema
```
reference/drama-script.md›
# 剧本还原
## 能力用途
基于大模型视频理解能力，将短剧视频转化为结构化剧本文本，识别并提取场景、人物、对话和情节等核心元素。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video drama-script`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--return-pkg`）只能写成 `--return-pkg=true` 或 `--return-pkg=false`，也可用裸 `--return-pkg`（等价 true）；禁止空格传值 `--return-pkg true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
- 数组参数（`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--video-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video drama-script \
--video-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 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 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `return_pkg` | `--return-pkg` | boolean | 否 | false | - | 控制任务结果的输出封装格式。true 时，所有任务产物会打包为 .tar.gz 压缩包，result_url 指向该压缩包，压缩包包含核心剧本 JSON、人物名及其图片、场景截图等分析结果；false 时，仅返回核心剧本数据，result_url 指向 Gzip 压缩的 JSON 文件 .json.gz。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 100 | 待处理短剧视频的 URL 列表。单次任务支持传入 1 个至 100 个视频文件，并按 video_urls 的数组顺序拼接视频后进行分析。视频输入支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 和 tos:// 四种协议来源，也支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流格式；不支持 HLS（M3U8）格式。单个视频文件时长不超过 120 分钟，单次任务所有视频累计时长不超过 300 分钟，视频必须包含内嵌硬字幕。适用于以人物对话和情节发展为核心的真人实拍短剧、长剧和电影；不适用于缺乏连贯真人剧情或人脸识别线索的动画、纪录片、广告和直播录屏。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.drama_script_task_id` | string / null | 否 | Cloud 终态 | 剧本还原任务 ID。 |
| `result.duration` | number / null | 否 | Cloud 终态 | 输入视频总时长，单位为秒。 |
| `result.result_url` | string | 否 | Cloud 终态 | 最终生成的剧本文件下载地址，为公网 URL；有效期为 24 小时，务必及时保存。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video drama-script --help
mediakit-cli video drama-script --schema
```
reference/enhance-video-fast.md›
# 视频画质增强极速版
## 能力用途
集成轻量级超分与智能画质增强，采用速度优先策略，高效兼顾处理效率与画面效果，尤其适用于处理时延敏感的业务场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video enhance-video-fast`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `bitrate_level` | `--bitrate-level` | string | 否 | "medium" | 枚举: ["low","medium","high"] | bitrate_level 是控制输出视频平均码率的目标码率档位，会影响输出视频的视觉质量和文件体积。可使用 low、medium、high：low 表示低码率，medium 表示中码率且为推荐档位，high 表示高码率。bitrate_level 非必填，默认为 medium。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `fps` | `--fps` | number | 否 | - | 最小值: 15；最大值: 120 | fps 用于指定目标帧率，单位为 fps，范围为 [15, 120]。建议 fps 不超过原片帧率的 4 倍。fps 非必填；未指定 fps 时，输出视频保持与原始片源一致的帧率。 |
| `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 | 否 | - | 枚举: ["240p","360p","480p","540p","720p","1080p","2k","4k"] | resolution 是目标分辨率档位，用于将视频超分到指定规格；支持 240p、360p、480p、540p、720p、1080p、2k、4k。resolution 非必填；resolution 与 resolution_limit 互斥，不得同时配置。 |
| `resolution_limit` | `--resolution-limit` | integer | 否 | - | 最小值: 128；最大值: 2160 | resolution_limit 用于指定目标分辨率的短边像素限制，范围为 [128, 2160]；系统会在保持原视频宽高比的前提下等比缩放到该短边限制值。resolution_limit 非必填；resolution_limit 与 resolution 互斥，不得同时配置。 |
| `video_url` | `--video-url` | string | 是 | - | - | video_url 是待增强视频的 URL。必须提供 video_url；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod://、火山引擎对象存储 tos:// 四种输入协议。输入支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；输入视频分辨率长边范围为 [360,2560]、短边范围为 [360,1440]，最高支持 2K。建议单个输入文件大小不超过 10 GB。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video enhance-video-fast \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频总时长，单位为秒。 |
| `result.fps` | 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 video enhance-video-fast --help
mediakit-cli video enhance-video-fast --schema
```
reference/enhance-video-generative.md›
# 生成式画质增强
## 能力用途
基于 Diffusion 扩散大模型技术提供生成式视频增强与修复，通过深度语义理解，智能补全和生成符合视频内容的真实细节，可修复视频在压缩或老化过程中损失的像素，最终产出自然、高保真的视频画面。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video enhance-video-generative`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `bitrate_level` | `--bitrate-level` | string | 否 | "medium" | 枚举: ["low","medium","high"] | bitrate_level 是控制输出视频平均码率的目标码率档位，会影响视频的视觉质量和最终文件体积；high 表示高码率，medium 表示中码率且为推荐档位，low 表示低码率；默认值为 medium。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `fps` | `--fps` | number | 否 | - | 最小值: 15；最大值: 120 | fps 指定目标帧率，单位为 fps；支持范围为 [15, 120]；建议不超过原片帧率的 4 倍；未指定 fps 时，输出视频保持与原始片源一致的帧率。 |
| `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" | 枚举: ["720p","1080p","2k"] | resolution 指定目标分辨率；支持 720p、1080p、2k；默认值为 720p。 |
| `video_url` | `--video-url` | string | 是 | - | - | video_url 是待增强的视频 URL；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；仅支持 SDR 视频；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；输入视频最高支持 1080p，长边范围为 [360,1920]，短边范围为 [360,1080]。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video enhance-video-generative \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | result.duration 是输出视频的总时长，单位为秒。 |
| `result.fps` | number | 否 | Cloud 终态 | result.fps 是输出视频的帧率。 |
| `result.resolution` | string | 否 | Cloud 终态 | result.resolution 是输出视频的分辨率。 |
| `result.video_url` | string | 否 | Cloud 终态 | result.video_url 是增强后的视频文件地址；未设置 media_output_destination 时，result.video_url 返回有效期为 24 小时的 HTTPS 临时下载链接，需要及时下载保存；设置 media_output_destination 后，result.video_url 返回 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 video enhance-video-generative --help
mediakit-cli video enhance-video-generative --schema
```
reference/enhance-video.md›
# 画质增强
## 能力用途
用于视频画质增强。利用 AI 算法对输入视频进行分析，并智能执行包括但不限于视频去噪、色彩增强、清晰度提升、瑕疵修复和超分辨率的一系列优化操作。提供 standard 和 professional 两种版本：standard 兼顾处理速度与视频画质，内置高频使用的 10 余种增强算法，适用于视频分发场景的画质增强；professional 提供极致画质增强，内置 30 余种深度 AI 增强算法，适用于影视级视频制作。不同版本会影响增强算法的强度、适用场景与计费。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video enhance-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `bit_depth` | `--bit-depth` | integer | 否 | 8 | 枚举: [8,10,12] | 目标色深，也称为位深。bit_depth 仅在 professional 版本支持设置，可选 8、10、12，默认 8。8 表示 8 bit 位深，使用 H.264 编码；10 表示 10 bit 位深，使用 H.265 编码；12 表示 12 bit 位深，使用 H.265 编码。 |
| `bitrate_level` | `--bitrate-level` | string | 否 | "medium" | 枚举: ["low","medium","high"] | 用于控制输出视频的平均码率，会影响视频的视觉质量和最终的文件体积。可选 low、medium、high；其中 high 表示高码率，medium 表示中码率，推荐使用，low 表示低码率；默认 medium。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `fps` | `--fps` | number | 否 | - | 最小值: 15；最大值: 120 | 目标帧率，单位为 fps，取值范围为 15 到 120。若未指定 fps，输出视频将保持与原始片源一致的帧率。建议 fps 不超过原片的 4 倍。 |
| `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 | 否 | - | 枚举: ["240p","360p","480p","540p","720p","1080p","2k","4k","8k"] | 目标分辨率档位，支持 240p、360p、480p、540p、720p、1080p、2k、4k、8k。可以使用 resolution 将视频超分到指定规格。resolution 与 resolution_limit 不可同时配置。 |
| `resolution_limit` | `--resolution-limit` | integer | 否 | - | 最小值: 128；最大值: 4320 | 目标分辨率的短边像素限制，取值范围为 128 到 4320。系统将根据 resolution_limit 在保持原视频宽高比的前提下等比缩放到该限制值。resolution_limit 与 resolution 不可同时配置。 |
| `scene` | `--scene` | string | 否 | "common" | 枚举: ["common","ugc","short_series","aigc","old_film"] | 用于选择一个针对特定业务场景的预设画质增强模板。scene 仅在 tool_version 为 standard 时生效，可选 common、ugc、short_series、aigc、old_film，默认 common。其中 common 表示通用模板，ugc 表示 UGC 短视频场景，short_series 表示短剧场景，aigc 表示 AIGC 内容场景，old_film 表示老片修复场景。 |
| `tool_version` | `--tool-version` | string | 否 | "standard" | 枚举: ["standard","professional"] | 影响增强算法的强度、适用场景与计费。可选 standard 和 professional，默认 standard。其中 standard 表示标准版，兼顾处理速度与视频画质，内置高频使用的 10 余种增强算法，覆盖主流播放平台画质要求，适用于视频分发场景的画质增强；professional 表示专业版，提供极致画质增强，保障镜头级画质效果，内置 30 余种深度 AI 增强算法，适用于影视级视频制作。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待增强的视频 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播的 vod://、火山引擎对象存储的 tos:// 输入协议。支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。建议单个输入文件大小不超过 10 GB。输入视频分辨率最高支持 2K，长边范围为 360 到 2560，短边范围为 360 到 1440。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video enhance-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.fps` | number | 否 | Cloud 终态 | 输出视频的帧率。 |
| `result.resolution` | string | 否 | Cloud 终态 | 输出视频的分辨率。 |
| `result.tool_version` | string | 否 | Cloud 终态 | 任务实际使用的工具版本。 |
| `result.video_url` | string | 否 | Cloud 终态 | 增强后的视频文件下载地址。未设置 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 video enhance-video --help
mediakit-cli video enhance-video --schema
```
reference/erase-video-subtitle-pro.md›
# 精细化字幕擦除
## 能力用途
用于字幕擦除（精细化版），对视频字幕进行高质量无痕擦除，并最大程度还原视频画面。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video erase-video-subtitle-pro`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 对象或对象数组参数（`--erase-ratio-location`、`--subtitle-filter`、`--time-segment-filter`）需传合法 JSON 字符串并整体加单引号，例如 `--erase-ratio-location '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video erase-video-subtitle-pro \
--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 生成、推断或补写。 |
| `erase_ratio_location` | `--erase-ratio-location` | array<object> | 否 | - | 最少项数: 0；最多项数: 20 | 配置擦除框位置数组后，系统仅在指定矩形框选区域内执行文本擦除。每个 location 由左上角与右下角两个顶点确定矩形擦除区域，坐标以画面左上角 (0, 0) 为原点、右下角为 (1, 1)，X 轴向右、Y 轴向下，使用相对画面宽高的归一化比例 [0,1]。最多支持 20 个擦除框。 |
| `erase_ratio_location[].bottom_right_x` | - | number | 是 | - | 最小值: 0；最大值: 1 | bottom_right_x 是框选区域右下角相对于视频左上角在 X 轴上的偏移比例，范围 [0,1]；0 与左边缘对齐，1 与右边缘对齐。 |
| `erase_ratio_location[].bottom_right_y` | - | number | 是 | - | 最小值: 0；最大值: 1 | bottom_right_y 是框选区域右下角相对于视频左上角在 Y 轴上的偏移比例，范围 [0,1]；0 与上边缘对齐，1 与下边缘对齐。 |
| `erase_ratio_location[].top_left_x` | - | number | 是 | - | 最小值: 0；最大值: 1 | top_left_x 是框选区域左上角相对于视频左上角在 X 轴上的偏移比例，范围 [0,1]；0 与左边缘对齐，1 与右边缘对齐。 |
| `erase_ratio_location[].top_left_y` | - | number | 是 | - | 最小值: 0；最大值: 1 | top_left_y 是框选区域左上角相对于视频左上角在 Y 轴上的偏移比例，范围 [0,1]；0 与上边缘对齐，1 与下边缘对齐。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `mode` | `--mode` | string | 否 | "Subtitle" | 枚举: ["Subtitle","Text"] | 字幕擦除模式，默认 Subtitle，支持 Subtitle 和 Text。Subtitle 模式擦除 OCR 检测为字幕的文本，默认仅处理视频画面下半部分（下方 50%）区域；配置 erase_ratio_location 时，只处理自定义擦除框与画面下半部分的交集。Text 模式擦除 OCR 检测为字幕及人名、地名等其他类型文本，不包含牌匾等场景文字；默认检测整个视频画面，配置 erase_ratio_location 时仅在指定擦除框内执行。 |
| `model_version` | `--model-version` | string | 否 | "v4" | 枚举: ["v4","v5"] | 擦除算法版本，支持 v4 和 v5，默认 v4。相比 V4，V5 优化 AIGC 生成视频擦除字幕后的闪烁问题、带阴影字幕的擦除效果和误擦问题，并提升处理速度。 |
| `output_encode_mode` | `--output-encode-mode` | string | 否 | "Quality" | 枚举: ["Quality","Size"] | 输出视频编码模式，默认 Quality。Quality 采用较高码率编码，画质更好，但文件体积可能更大；Size 在保证一定画质的前提下使输出码率接近源文件。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `subtitle_filter` | `--subtitle-filter` | object | 否 | - | - | subtitle_filter 通过文字高度和水平居中程度帮助系统更准确地判断哪些文本属于字幕，避免误擦大标题、台标、水印等非字幕文本。仅当文本高度不低于下限、不高于上限且水平方向足够居中时，文本才会被判定为字幕并擦除，大标题、台标、水印等文本会被排除。仅在 mode 为 Subtitle 时生效，不传时使用系统默认值。 |
| `subtitle_filter.center_offset_ratio` | - | number | 否 | - | 最小值: 0；最大值: 1 | center_offset_ratio 是文字区域中心相对视频宽度中心的最大偏离比例，范围 [0,1]，默认 0.08；超过该比例的文本不会被判定为字幕。 |
| `subtitle_filter.max_text_height_ratio` | - | number | 否 | - | 最小值: 0；最大值: 1 | max_text_height_ratio 是相对视频高度的文字高度最大比例，范围 [0,1]；高于该高度的文本不会被判定为字幕；不传时 v4 默认 0.2（20%），v5 默认 0.1（10%）。 |
| `subtitle_filter.min_text_height_ratio` | - | number | 否 | - | 最小值: 0；最大值: 1 | min_text_height_ratio 是相对视频高度的文字高度最小比例，范围 [0,1]，默认 0.01（1%）；低于该高度的文本不会被判定为字幕。 |
| `time_segment_filter` | `--time-segment-filter` | object | 否 | - | - | 按 mode 对指定时间段执行或跳过擦除；不配置则对整段视频生效，适用于只擦除正片或保留片头、片尾字幕等场景。 |
| `time_segment_filter.mode` | - | string | 是 | - | 枚举: ["skip","selected"] | skip 跳过 segments 中列出的时间段并擦除其余部分；selected 仅擦除 segments 中列出的时间段。 |
| `time_segment_filter.segments` | - | array<object> | 是 | - | 最少项数: 1 | segments 时间段列表至少包含 1 个时间段。 |
| `time_segment_filter.segments[].end_time` | - | number | 是 | - | 最小值: 0 | end_time 是以秒为单位的片段结束时间，需大于 start_time。 |
| `time_segment_filter.segments[].start_time` | - | number | 是 | - | 最小值: 0 | start_time 是以秒为单位的片段起始时间，取值大于等于 0。 |
| `video_url` | `--video-url` | string | 是 | - | - | 支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议，支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式，输入分辨率最高支持 2K，输出分辨率最高支持 1080P。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | result.duration 表示输出视频总时长，单位为秒。 |
| `result.video_url` | string | 否 | Cloud 终态 | result.video_url 是擦除字幕后的视频地址；未设置 media_output_destination 时返回有效期 24 小时的 HTTPS 临时下载链接，请及时下载保存；设置后返回 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 video erase-video-subtitle-pro --help
mediakit-cli video erase-video-subtitle-pro --schema
```
reference/erase-video-subtitle.md›
# 字幕擦除（标准版）
## 能力用途
智能检测并擦除视频画面中已有的硬字幕，保留原始背景。
支持格式：主流视频格式如mp4、flv、ts、avi、mov、wmv、mkv。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video erase-video-subtitle`
- 生命周期：异步
- 返回方式：返回 `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 | 是 | - | - | video_url 是待擦除字幕的视频 URL，支持公网 HTTP/HTTPS URL、本地文件路径、vod://、tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。输入视频最高支持 2K 分辨率，输出分辨率最高支持 1080P。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video erase-video-subtitle \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | duration 表示输出视频的总时长，单位为秒。 |
| `result.video_url` | string | 否 | Cloud 终态 | video_url 表示擦除字幕后的视频文件地址。设置 media_output_destination 后，video_url 返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>；未设置 media_output_destination 时，video_url 默认返回一个 HTTPS 临时下载链接，有效期为 24 小时。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video erase-video-subtitle --help
mediakit-cli video erase-video-subtitle --schema
```
reference/extract-frames.md›
# 视频抽帧
## 能力用途
从视频中抽取截图，截图结果支持用于视频封面、预览图、雪碧图或其他视频理解任务的输入。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video extract-frames`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-sprite`）只能写成 `--enable-sprite=true` 或 `--enable-sprite=false`，也可用裸 `--enable-sprite`（等价 true）；禁止空格传值 `--enable-sprite true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video extract-frames \
--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 生成、推断或补写。 |
| `enable_sprite` | `--enable-sprite` | boolean | 否 | false | - | 默认 false。设为 true 时输出包含所有截图的雪碧图；设为 false 时输出多张独立截图。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `scale_long` | `--scale-long` | integer | 否 | - | 最小值: 0；最大值: 4096 | scale_long 最小值为 0，最大值为 4096。输出图片长边不得超过原始视频长边。按长边缩放时，输出图片短边按原始比例自适应。enable_sprite 为 true 时，scale_long 定义单张小图的长边。同时设置 scale_long 和 scale_short 时保持原始宽高比，并分别约束长边和短边。 |
| `scale_short` | `--scale-short` | integer | 否 | - | 最小值: 0；最大值: 4096 | scale_short 最小值为 0，最大值为 4096。输出图片短边不得超过原始视频短边。按短边缩放时，输出图片长边按原始比例自适应。enable_sprite 为 true 时，scale_short 定义单张小图的短边。同时设置 scale_long 和 scale_short 时保持原始宽高比，并分别约束长边和短边。 |
| `scene_change_threshold` | `--scene-change-threshold` | number | 否 | 0.1 | 最小值: 0；最大值: 1 | scene_change_threshold 默认值为 0.1。scene_change_threshold 必须大于 0 且必须小于 1。scene_change_threshold 仅在 snapshot_type 为 SceneChange 时生效。scene_change_threshold 越小，场景变化检测越敏感，可能产生更多截图。 |
| `snapshot_limit` | `--snapshot-limit` | integer | 否 | - | 最小值: 1；最大值: 1000 | snapshot_limit 最小值为 1，最大值为 1000。实际输出的截图数可能小于 snapshot_limit。snapshot_limit 仅在 snapshot_type 为 TimeInterval 或 SceneChange 时生效。enable_sprite 为 true 时，snapshot_limit 表示雪碧图大图数量上限，小图数量上限为 snapshot_limit*sprite_rows*sprite_cols。 |
| `snapshot_type` | `--snapshot-type` | string | 否 | "TimeInterval" | 枚举: ["TimeInterval","SpecifiedTime","SpecifiedFrames","SceneChange"] | snapshot_type 决定抽帧的具体方式，默认为 TimeInterval，支持 TimeInterval、SpecifiedTime、SpecifiedFrames 和 SceneChange 四个字面值。TimeInterval 表示按时间间隔抽帧，并需配合 time_interval。SpecifiedTime 表示按指定时间点抽帧，并需配合 specified_time。SpecifiedFrames 表示按指定帧号抽帧，并需配合 specified_frames。SceneChange 表示按场景变化抽帧，并需配合 scene_change_threshold。 |
| `specified_frames` | `--specified-frames` | array<integer> | 否 | - | 最少项数: 1；最多项数: 2；元素枚举: [0,-1] | specified_frames 当前仅支持 0 表示视频首帧、-1 表示视频尾帧，最多支持 2 个值。 |
| `specified_time` | `--specified-time` | array<number> | 否 | - | 最少项数: 1；最多项数: 1000 | specified_time 中时间点的单位为秒，支持最多 3 位小数，最多支持 1000 个时间点。 |
| `sprite_cols` | `--sprite-cols` | integer | 否 | 10 | 最小值: 1；最大值: 100 | sprite_cols 表示雪碧图在 X 轴水平方向的小图数量，默认值为 10，最小值为 1，最大值为 100。sprite_cols 仅在 enable_sprite 为 true 时生效。过大的雪碧图行列数可能导致任务失败，雪碧图建议单边不超过 16384 像素。 |
| `sprite_rows` | `--sprite-rows` | integer | 否 | 10 | 最小值: 1；最大值: 100 | sprite_rows 表示雪碧图在 Y 轴垂直方向的小图数量，默认值为 10，最小值为 1，最大值为 100。sprite_rows 仅在 enable_sprite 为 true 时生效。过大的雪碧图行列数可能导致任务失败，雪碧图建议单边不超过 16384 像素。 |
| `time_interval` | `--time-interval` | number | 否 | 1 | 最小值: 0.001 | time_interval 默认值为 1，单位为秒，支持最多 3 位小数，必须大于 0.001。time_interval 仅在 snapshot_type 为 TimeInterval 时生效。 |
| `video_url` | `--video-url` | string | 是 | - | - | video_url 是待处理的视频 URL，支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 和 tos:// 四种输入协议。视频输入支持 mp4、mov、mkv、flv、ts、avi、wmv 等主流视频格式。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.snapshot_count` | integer | 否 | Cloud 终态 | snapshot_count 是成功生成的截图总数；雪碧图模式下，snapshot_count 表示雪碧图中的小图数量。 |
| `result.snapshots` | array<object> | 否 | Cloud 终态 | snapshots 是截图结果列表，每个对象包含一张截图的信息。 |
| `result.snapshots[].image_url` | string | 否 | Cloud 终态 | image_url 是截图下载地址，有效期为 24 小时，需及时保存产物。enable_sprite 为 true 时，snapshots 数组中的 image_url 指向合成后的雪碧图大图。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video extract-frames --help
mediakit-cli video extract-frames --schema
```
reference/extract-video-invisible-watermark.md›
# 提取视频暗水印
## 能力用途
从已嵌入暗水印的视频中解析并还原隐藏的数字信息；如果同一视频被多次嵌入暗水印，也能够提取出所有水印信息。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video extract-video-invisible-watermark`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待提取暗水印的视频 URL，必选。支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、mov、mkv、flv、ts、avi、wmv 等主流视频格式；分辨率最高支持 4K。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video extract-video-invisible-watermark \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频的总时长，单位为秒。 |
| `result.watermark_contents` | array<object> | 否 | Cloud 终态 | 提取到的暗水印数字信息列表，按系统提取顺序返回；若视频中嵌入了多次暗水印，可能返回多条结果；如果未提取到任何暗水印，列表为空。 |
| `result.watermark_contents[].watermark_content` | string | 否 | Cloud 终态 | 提取到的暗水印数字信息字符串。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video extract-video-invisible-watermark --help
mediakit-cli video extract-video-invisible-watermark --schema
```
reference/face-blur-video.md›
# 视频人脸打码
## 能力用途
视频人脸打码可自动精准识别视频画面中的人脸区域，并对所有人脸进行模糊或马赛克处理，适用于需要保护人物五官隐私的场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video face-blur-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--upright-face-only`）只能写成 `--upright-face-only=true` 或 `--upright-face-only=false`，也可用裸 `--upright-face-only`（等价 true）；禁止空格传值 `--upright-face-only true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video face-blur-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 生成、推断或补写。 |
| `face_box_expand` | `--face-box-expand` | number | 否 | 0.2 | 最小值: 0；最大值: 1 | 人脸边界框扩展比例，范围大于 0.0 且不超过 1.0，默认值为 0.2。系统将根据该比例在检测到的人脸区域基础上向外扩展打码范围。 |
| `face_confidence` | `--face-confidence` | number | 否 | 0.35 | 最小值: 0.1；最大值: 1 | 人脸检测置信度阈值，范围 0.1 至 1.0，默认值为 0.35。低于此阈值的检测结果将被丢弃。 |
| `mask_mode` | `--mask-mode` | string | 否 | "mosaic" | 枚举: ["mosaic","blur"] | 人脸打码方式：mosaic 表示马赛克，为默认值；blur 表示高斯模糊。 |
| `mask_strength` | `--mask-strength` | string | 否 | "medium" | 枚举: ["low","medium","high"] | 人脸打码强度：low 表示低强度；medium 表示中强度，为默认值；high 表示高强度。 |
| `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 生成、推断或补写。 |
| `upright_face_only` | `--upright-face-only` | boolean | 否 | true | - | 是否只对正向人脸打码。true 仅处理正脸；false 连同侧脸、歪头等非正向人脸也一并打码。不传时默认 true（只处理正向人脸） |
| `video_url` | `--video-url` | string | 是 | - | - | 待打码的视频 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；分辨率最高支持 4K，推荐使用 1080P 以获得最佳处理效果；帧率需在 25~60 范围内；视频时长不得超过 10 分钟。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频总时长，单位为秒，可用于计量计费。 |
| `result.video_url` | string | 否 | Cloud 终态 | 已完成人脸打码的视频文件地址。未设置 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 video face-blur-video --help
mediakit-cli video face-blur-video --schema
```
reference/face-swap-video.md›
# 视频人脸融合
## 能力用途
将用户提供的目标人脸融合替换到视频中的人物上，输出高质量换脸视频，主要适用于生成式视频脱敏需要换脸的场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video face-swap-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 对象或对象数组参数（`--face-mappings`）需传合法 JSON 字符串并整体加单引号，例如 `--face-mappings '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video face-swap-video \
--video-url <video_url> \
--face-mappings '[{...}]'
```
仅使用用户真实输入替换占位符；可选 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 生成、推断或补写。 |
| `face_mappings` | `--face-mappings` | array<object> | 是 | - | 最少项数: 1；最多项数: 1 | 人脸映射列表。当前仅支持单人换脸，传入一项即可。 |
| `face_mappings[].target_face_url` | - | string | 是 | - | - | 目标人脸图片 URL，支持 jpeg、png；支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议。建议分辨率为 256×256～1080×1080；要求为清晰可见、无遮挡的正脸；不支持动漫人脸。 |
| `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，当前仅支持 MP4；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议。时长不得超过 10 分钟（600 秒）；分辨率不得超过 1080P。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输出视频总时长，单位为秒。 |
| `result.video_url` | string | 否 | Cloud 终态 | 已完成人脸融合的视频文件地址。设置 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 video face-swap-video --help
mediakit-cli video face-swap-video --schema
```
reference/generate-highlights-microdrama.md›
# 高光智剪-短剧
## 能力用途
可用于短剧高光智剪，基于输入剧集的角色和剧情故事线理解提取高光片段，并按时长、产出个数、顺剪或跳剪等要求生成高光混剪、单集预告等视频。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video generate-highlights-microdrama`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-generate-video`、`--enable-return-poster`、`--enable-segment-tag`）只能写成 `--enable-generate-video=true` 或 `--enable-generate-video=false`，也可用裸 `--enable-generate-video`（等价 true）；禁止空格传值 `--enable-generate-video true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
- 数组参数（`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--video-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--edit-param`、`--highlight-cuts-param`、`--opening-hook-param`）需传合法 JSON 字符串并整体加单引号，例如 `--edit-param '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video generate-highlights-microdrama \
--video-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 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 可打印字符。 默认不传。用户明确指定时原样使用；用户明确要求重试时，同一逻辑请求的重试链必须复用同一 token。已有 token 时必须复用原值；此前请求未带 token 时，可从本次重试开始创建一次并持续复用，但该 token 不对此前请求提供追溯幂等。业务参数变化视为新请求，不得复用旧 token。不得为每次尝试生成不同值。CLI/MCP runtime 不判断重试意图，也不自动生成 token。 |
| `edit_param` | `--edit-param` | object | 否 | - | - | 高光视频剪辑配置用于控制最终输出视频的视觉风格；留空时默认使用基础剪辑模式。enable_generate_video 为 false 时，该配置将被忽略。 |
| `edit_param.mode` | - | string | 是 | "BasicEdit" | 枚举: ["BasicEdit","TemplateEdit"] | 成片剪辑模式决定是否使用视觉模板，默认为 BasicEdit；支持 BasicEdit 和 TemplateEdit。BasicEdit 表示基础剪辑，不添加额外视觉元素；TemplateEdit 表示模板剪辑，使用指定的短剧三要素视觉模板。 |
| `edit_param.template_edit` | - | object | 否 | - | - | 短剧模板剪辑参数不是无条件必选；当 mode 为 TemplateEdit 时必须填写。 |
| `edit_param.template_edit.hint` | - | string | 否 | - | 最长长度: 20 | 短剧提示语将显示在画面左侧或右侧，长度不得超过 20 个字符。 |
| `edit_param.template_edit.template` | - | string | 否 | "热门短剧1" | 枚举: ["热门短剧1","热门短剧2","热门短剧3","热门短剧4","热门短剧5"] | 短剧三要素视觉模板名称决定剧名、角标、提示语的样式和位置，默认为热门短剧1；支持 热门短剧1、热门短剧2、热门短剧3、热门短剧4、热门短剧5。 |
| `edit_param.template_edit.title` | - | string | 否 | - | 最长长度: 22 | 短剧名称将显示在视频画面中，长度不得超过 22 个字符。 |
| `enable_generate_video` | `--enable-generate-video` | boolean | 否 | true | - | 是否生成高光混剪视频，默认为 true。true 时生成并输出高光混剪视频；false 时不生成高光混剪视频，传入的 edit_param 将被忽略。 |
| `enable_return_poster` | `--enable-return-poster` | boolean | 否 | false | - | 是否在任务结果中返回混剪视频的封面图 URL，默认为 false。true 时返回混剪视频的封面图 URL；false 时不返回封面图。 |
| `enable_segment_tag` | `--enable-segment-tag` | boolean | 否 | - | - | 是否返回高光片段和分镜标签，默认为 false。true 时在 result.mixvideo_info.clips 与 result.storyboard_info 中额外返回 tags 字段；false 时不返回 tags 字段。 |
| `highlight_cuts_param` | `--highlight-cuts-param` | object | 否 | - | - | 高光智剪参数配置用于控制最终输出视频的时长与个数；留空时默认使用热门短剧1模板。 |
| `highlight_cuts_param.cut_mode` | - | string | 否 | "Mixed" | 枚举: ["Mixed","Sequential"] | 剪辑模式默认为 Mixed；支持 Mixed 和 Sequential。Mixed 表示混剪，打乱高光片段的原始顺序；Sequential 表示顺剪，保持高光片段的原始时间顺序。 |
| `highlight_cuts_param.enable_storyboard` | - | boolean | 否 | false | - | 控制是否在任务结果中输出详细的分镜信息 storyboard_info，默认为 false。 |
| `highlight_cuts_param.highlight_ending_prompt` | - | string | 否 | - | - | 高光混剪结尾钩子选取偏好，仅在 cut_mode 为 Mixed 的混剪模式下生效。 |
| `highlight_cuts_param.highlight_segment_prompt` | - | string | 否 | - | - | 高光片段选取偏好，仅在 cut_mode 为 Mixed 的混剪模式下生效。 |
| `highlight_cuts_param.highlight_start_prompt` | - | string | 否 | - | - | 高光混剪开头起播点选取偏好，仅在 cut_mode 为 Mixed 的混剪模式下生效。 |
| `highlight_cuts_param.max_duration` | - | number | 否 | 180 | - | 期望输出高光视频的最大时长，默认为 180。 |
| `highlight_cuts_param.max_number` | - | integer | 否 | 6 | - | 最多输出的高光视频数量，默认为 6。 |
| `highlight_cuts_param.min_duration` | - | number | 否 | 30 | - | 期望输出高光视频的最小时长，默认为 30。 |
| `highlight_cuts_param.user_preferred_segments` | - | array<object> | 否 | - | - | 用户期望优先选用的原片内容或片段，支持填写多个，仅在 cut_mode 为 Mixed 的混剪模式下生效。 |
| `highlight_cuts_param.user_preferred_segments[].end_time` | - | number | 否 | - | - | 优先片段在该输入视频中的结束时间，单位为秒。 |
| `highlight_cuts_param.user_preferred_segments[].episode` | - | integer | 是 | - | 最小值: 0 | 优先选用的输入视频序号，从 0 开始计数；仅含该序号表示整集优先。 |
| `highlight_cuts_param.user_preferred_segments[].start_time` | - | number | 否 | - | - | 优先片段在该输入视频中的起始时间，单位为秒；与 end_time 一并提供时，表示该集指定时间区间优先。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置；支持将处理产物存储至火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD 时设为 `vod://<您的空间名>`，存储至 TOS 时设为 `tos://<您的桶名>`。设置后，任务结果中的 `url` 相关字段返回 `vod://` 或 `tos://` 格式的资源地址，不再返回临时下载地址。首次使用前需按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `mode` | `--mode` | string | 否 | "StorylineCuts" | 枚举: ["StorylineCuts"] | 当前版本固定为 StorylineCuts。 |
| `opening_hook_param` | `--opening-hook-param` | object | 否 | - | - | 精彩前置参数用于控制是否在视频开头添加一个极具吸引力的钩子片段来留住观众；留空时默认在视频开头添加精彩前置片段。 |
| `opening_hook_param.enable_opening_hook` | - | boolean | 否 | true | - | 是否启用精彩前置开场钩子，默认为 true。 |
| `opening_hook_param.max_duration` | - | number | 否 | 15 | - | 开场钩子片段的最大时长，默认为 15。 |
| `opening_hook_param.min_clip_duration` | - | number | 否 | 5 | - | 构成开场钩子的单个高光片段的最小持续时长，默认为 5。 |
| `opening_hook_param.min_duration` | - | number | 否 | 5 | - | 开场钩子片段的最小时长，默认为 5。 |
| `opening_hook_param.min_score` | - | number | 否 | 3 | - | 构成开场钩子的单个高光片段所需达到的最低高光分，范围为 [1, 5]，默认为 3。 |
| `opening_hook_param.opening_hook_prompt` | - | string | 否 | - | - | 精彩前置片段选取标准，用自然语言描述开头钩子的筛选偏好。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID；不传时默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以按队列对应的项目进行分账。队列可创建和管理，系统会自动分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_ending_mode` | `--video-ending-mode` | string | 否 | - | 枚举: ["ReuseMainEnding","SmartSelect"] | 视频结尾选取模式默认为 ReuseMainEnding；支持 ReuseMainEnding 和 SmartSelect。ReuseMainEnding 时优先复用正片剧集结尾；SmartSelect 时使用智能选取模式。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 100 | 待处理的短剧原片视频 URL 列表。支持公网 HTTP/HTTPS URL、本地文件路径、来源于火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；输入分辨率最高支持 1080p。所有输入文件的累计总时长不得超过 45 分钟。输入素材必须同时包含视频流和音频流，视频画面下半部分必须包含清晰居中的中文字幕，音频轨道中必须包含清晰可识别的中文对话文本。 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
### 任务结果查询
提交成功后会返回 `task_id`，再执行 `mediakit-cli shared query-task --task-id <task_id>` 查询。
- 当前命令：`mediakit-cli video generate-highlights-microdrama`
- 推荐查询：`mediakit-cli shared query-task --task-id <task_id>`
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video generate-highlights-microdrama --help
mediakit-cli video generate-highlights-microdrama --schema
```
reference/generate-highlights-minigame.md›
# 高光智剪-小游戏
## 能力用途
支持识别小游戏录屏视频中的核心玩法与高光事件，例如连击、通关、极限操作，并快速生成用于买量推广的视频素材。可选提供游戏名称、玩法描述和高光定义，辅助更精准地识别精彩内容。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video generate-highlights-minigame`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-generate-video`）只能写成 `--enable-generate-video=true` 或 `--enable-generate-video=false`，也可用裸 `--enable-generate-video`（等价 true）；禁止空格传值 `--enable-generate-video true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
- 数组参数（`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--video-urls "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--minigame-info`）需传合法 JSON 字符串并整体加单引号，例如 `--minigame-info '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video generate-highlights-minigame \
--video-urls "url1,url2"
```
仅使用用户真实输入替换占位符；可选 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 生成、推断或补写。 |
| `enable_generate_video` | `--enable-generate-video` | boolean | 否 | true | - | 控制是否生成高光混剪视频，默认 true。true 时生成并输出高光混剪视频；false 时不生成高光混剪视频。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `minigame_info` | `--minigame-info` | object | 否 | - | - | 可选的小游戏描述信息，建议填写以辅助模型更精准地识别高光内容。 |
| `minigame_info.highlight_definition` | - | string | 否 | - | 最长长度: 5000 | 游戏高光时刻或精彩瞬间定义，例如一次消除多个方块或躲避所有障碍物通关。 |
| `minigame_info.name` | - | string | 否 | - | 最长长度: 5000 | 游戏名称，用于标识游戏内容。 |
| `minigame_info.play_definition` | - | string | 否 | - | 最长长度: 5000 | 游戏玩法规则或核心特点描述。 |
| `mode` | `--mode` | string | 否 | "HighlightExtract" | 枚举: ["HighlightExtract"] | 高光提取模式，当前版本固定为 HighlightExtract。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 1 | 待处理小游戏视频 URL 列表。单次任务仅支持输入 1 个视频文件；支持公网 HTTP/HTTPS、本地文件路径、视频点播 vod:// 和对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；输入文件时长不得超过 10 分钟；输入分辨率最高支持 1080p。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输入视频总时长，单位为秒。 |
| `result.mixvideo_info` | array<object> | 否 | Cloud 终态 | 高光混剪视频信息列表，每项包含构成该混剪的高光片段。 |
| `result.mixvideo_info[].clips` | array<object> | 否 | Cloud 终态 | 构成当前混剪视频的高光片段对象列表。 |
| `result.mixvideo_info[].clips[].clip_type` | string | 否 | Cloud 终态 | 片段类型，HighlightClip 代表普通高光片段。 |
| `result.mixvideo_info[].clips[].cut_end_time` | number | 否 | Cloud 终态 | 片段在最终混剪视频中的结束时间，单位为秒。 |
| `result.mixvideo_info[].clips[].cut_start_time` | number | 否 | Cloud 终态 | 片段在最终混剪视频中的起始时间，单位为秒。 |
| `result.mixvideo_info[].clips[].score` | number | 否 | Cloud 终态 | 分数越高表示片段越精彩。 |
| `result.mixvideo_info[].clips[].source_end_time` | number | 否 | Cloud 终态 | 片段在原始视频中的结束时间，单位为秒。 |
| `result.mixvideo_info[].clips[].source_start_time` | number | 否 | Cloud 终态 | 片段在原始视频中的起始时间，单位为秒。 |
| `result.mixvideo_info[].clips[].source_video_index` | integer | 否 | Cloud 终态 | 该片段在输入视频列表中的来源索引位置；小游戏高光智剪仅支持输入单个视频，来源索引固定为 0。 |
| `result.mixvideo_info[].mixvideo_index` | integer | 否 | Cloud 终态 | 混剪视频索引，与 video_urls 的位置一一对应，并从 0 开始。 |
| `result.mixvideo_info[].video_url` | string | 否 | Cloud 终态 | 当前混剪信息项对应的混剪视频地址。enable_generate_video 为 false 时不返回；未设置 media_output_destination 时，返回有效期为 24 小时的 HTTPS 临时下载链接；设置 media_output_destination 后，返回 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key> 格式的存储地址。 |
| `result.video_urls` | array<string> | 否 | Cloud 终态 | 最终生成的高光混剪视频地址列表。enable_generate_video 为 false 时不返回；未设置 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 video generate-highlights-minigame --help
mediakit-cli video generate-highlights-minigame --schema
```
reference/generate-highlights-movie.md›
# 高光智剪-影视拆条
## 能力用途
支持面向电影、电视剧等长视频内容，按剧情故事线识别高光并拆分成多段指定时长的高光片段，用于影视合集分发的短视频素材；算法会识别并去除景色铺垫、缓慢运镜、片头片尾曲等低密度信息；每段拆条带有高光前置开场与结尾钩子设计。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video generate-highlights-movie`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-generate-video`）只能写成 `--enable-generate-video=true` 或 `--enable-generate-video=false`，也可用裸 `--enable-generate-video`（等价 true）；禁止空格传值 `--enable-generate-video true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
- 对象或对象数组参数（`--highlight-cuts-param`、`--opening-hook-param`）需传合法 JSON 字符串并整体加单引号，例如 `--highlight-cuts-param '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video generate-highlights-movie \
--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 生成、推断或补写。 |
| `enable_generate_video` | `--enable-generate-video` | boolean | 否 | true | - | enable_generate_video 默认值为 true；为 true 时生成拆条视频文件，并在结果中返回 video_urls；为 false 时仅输出时间戳、评分、标题等片段元信息，不生成视频文件，可用于自定义二次剪辑。 |
| `highlight_cuts_param` | `--highlight-cuts-param` | object | 否 | - | - | highlight_cuts_param 控制每段拆条的目标时长范围以及是否返回详细片段时间线信息；留空时默认生成 90\-180 秒的拆条片段。 |
| `highlight_cuts_param.enable_detailed_info` | - | boolean | 否 | false | - | enable_detailed_info 默认值为 false；控制是否在 clips 中输出每段拆条的片段类型、评分及原始视频和拆条视频中的起止时间等详细信息。 |
| `highlight_cuts_param.max_duration` | - | number | 否 | 180 | 最小值: 1；最大值: 600 | max_duration 表示单个拆条片段的最大时长，单位为秒；默认值为 180 秒；范围为 1 到 600；建议不超过 180 秒（3 分钟）以贴合短视频平台分发节奏。 |
| `highlight_cuts_param.min_duration` | - | number | 否 | 90 | 最小值: 1；最大值: 600 | min_duration 表示单个拆条片段的最短时长，单位为秒；默认值为 90 秒；范围为 1 到 600。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `opening_hook_param` | `--opening-hook-param` | object | 否 | - | - | opening_hook_param 控制是否在每个拆条片段开头拼接最精彩的钩子片段；留空时默认添加 5\-15 秒的高光前置。 |
| `opening_hook_param.is_enabled` | - | boolean | 否 | true | - | is_enabled 默认值为 true；为 true 时系统自动提取最精彩片段置于拆条视频开头；为 false 时按原始剧情顺序输出拆条视频。 |
| `opening_hook_param.max_duration` | - | number | 否 | 15 | 最小值: 0；最大值: 60 | opening_hook_param.max_duration 默认值为 15 秒，范围为 0 到 60。 |
| `opening_hook_param.min_clip_duration` | - | number | 否 | 5 | 最小值: 0；最大值: 60 | min_clip_duration 是构成高光前置的单个片段最短时长，用于避免碎片过多造成频闪；默认值为 5；范围为 0 到 60。 |
| `opening_hook_param.min_duration` | - | number | 否 | 5 | 最小值: 0；最大值: 60 | opening_hook_param.min_duration 默认值为 5 秒，范围为 0 到 60。 |
| `opening_hook_param.min_score` | - | number | 否 | 4 | 最小值: 0；最大值: 5 | min_score 是筛选高光前置片段的最低评分，数值越高表示筛选标准越严格；默认值为 4；范围为 0 到 5。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | video_url 是待处理的影视视频源 URL；支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 和 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；单次任务仅支持单个视频文件；输入视频最高支持 1080p 分辨率，时长不得超过 180 分钟，必须同时包含视频流和音频流；输入更适合电影，也适用于电视剧等长视频内容，不建议用于纯综艺、纪录片、广告或纯 BGM 视频；建议音频轨道包含清晰可识别的中文对话文本，以帮助算法准确理解剧情逻辑。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.input_duration` | number | 否 | Cloud 终态 | input_duration 是输入视频总时长，单位为秒。 |
| `result.result_cuts_info` | array<object> | 否 | Cloud 终态 | result_cuts_info 的条目顺序与 video_urls 一致。 |
| `result.result_cuts_info[].clips` | array<object> | 否 | Cloud 终态 | clips 仅在 highlight_cuts_param.enable_detailed_info 为 true 时返回。 |
| `result.result_cuts_info[].clips[].cut_end_time` | number / null | 否 | Cloud 终态 | cut_end_time 是片段在最终拆条视频中的结束时间点，单位为秒。 |
| `result.result_cuts_info[].clips[].cut_start_time` | number / null | 否 | Cloud 终态 | cut_start_time 是片段在最终拆条视频中的起始时间点，单位为秒。 |
| `result.result_cuts_info[].clips[].score` | number / null | 否 | Cloud 终态 | score 是片段高光评分，范围为 [1, 5]。 |
| `result.result_cuts_info[].clips[].source_end_time` | number / null | 否 | Cloud 终态 | source_end_time 是片段在原始视频中的结束时间点，单位为秒。 |
| `result.result_cuts_info[].clips[].source_start_time` | number / null | 否 | Cloud 终态 | source_start_time 是片段在原始视频中的起始时间点，单位为秒。 |
| `result.result_cuts_info[].clips[].type` | string | 否 | Cloud 终态 | type 表示片段类型：OpeningHook（高光前置）或 HighlightClip（高光主体）。 |
| `result.result_cuts_info[].duration` | number / null | 否 | Cloud 终态 | duration 是拆条视频实际时长，单位为秒。 |
| `result.result_cuts_info[].size` | integer / string / null | 否 | Cloud 终态 | size 是拆条视频文件大小，单位为字节。 |
| `result.result_cuts_info[].title` | string | 否 | Cloud 终态 | title 是算法基于剧情自动生成的片段标题或内容简述。 |
| `result.result_cuts_info[].video_url` | string | 否 | Cloud 终态 | video_url 是该拆条片段对应的视频地址；未生成视频时 video_url 为空字符串；video_url 的有效期为 24 小时，需及时保存。 |
| `result.video_urls` | array<string> | 否 | Cloud 终态 | enable_generate_video 为 false 或算法未成功生成视频时，video_urls 为空。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video generate-highlights-movie --help
mediakit-cli video generate-highlights-movie --schema
```
reference/martencode-video.md›
# 极智超清
## 能力用途
极智超清在转码时智能分析视频的场景、动作、内容和纹理，选择最优编码参数，以相对较低码率输出主观画质更优的视频，降低带宽成本并改善用户视觉体验。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video martencode-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--metadata-keep-tags`）传多个值时用逗号分隔并整体加引号，例如 `--metadata-keep-tags "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--audio`、`--metadata-add-tags`、`--video`）需传合法 JSON 字符串并整体加单引号，例如 `--audio '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video martencode-video \
--video-url <video_url> \
--container-format <container_format> \
--video <video>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio` | `--audio` | object | 否 | - | - | 音频转码参数配置可省略；未传 audio 时，音频使用默认参数转码：编码格式为 aac，其余参数跟随源文件。 |
| `audio.bitrate_kbps` | - | integer | 是 | 128 | 最小值: 10；最大值: 500 | 音频码率，单位 Kbps，支持 10 至 500，默认 128；未设置时输出音频码率与原始音频一致。 |
| `audio.bitrate_mode` | - | string | 是 | "cbr" | 枚举: ["cbr","cae"] | 音频码率控制模式，支持 cbr、cae，默认 cbr。cbr 仅在 video.codec=h264 时支持，会尝试使音频流每一秒保持在 audio.bitrate_kbps 设定码率，适合对带宽稳定性要求高的流式传输场景；cae 仅在 audio.codec=aac 时支持，会根据音频复杂度动态调整瞬时码率，并确保整个文件平均码率接近 audio.bitrate_kbps 目标值。 |
| `audio.channels` | - | integer | 否 | 2 | 枚举: [1,2] | 声道数可省略，支持 1、2，默认 2；1 表示单声道，2 表示双声道。 |
| `audio.codec` | - | string | 是 | "aac" | 枚举: ["aac"] | 音频编码格式，支持 aac，默认 aac。 |
| `audio.sample_rate` | - | integer | 是 | 44100 | 枚举: [8000,11025,12000,16000,22050,24000,32000,44100,48000,64000,88200,96000] | 音频采样率，单位 Hz，支持 8000、11025、12000、16000、22050、24000、32000、44100、48000、64000、88200、96000，默认 44100。 |
| `audio.volume_integrated_loudness` | - | number | 否 | -12 | 最小值: -70；最大值: -5 | 音频整体感知音量，单位 LUFS，可省略，支持 -70 至 -5，默认 -12。 |
| `audio.volume_loudness_range` | - | number | 否 | 7 | 最小值: 1；最大值: 20 | 响度范围用于调节最响亮和最安静部分差异，单位 LU，可省略，支持 1 至 20，默认 7；在 audio.volume_method=2Pass 时生效。 |
| `audio.volume_method` | - | string | 否 | - | 枚举: ["2Pass"] | 音量均衡算法可省略；未设置时不处理音量。2Pass 启用两阶段响度分析与处理，且三个响度参数生效。 |
| `audio.volume_true_peak` | - | number | 否 | 0 | 最小值: -9；最大值: 0 | 音频最高上限用于防止削波失真，单位 dBTP，可省略，支持 -9 至 0，默认 0。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `container_format` | `--container-format` | string | 是 | "MP4" | 枚举: ["MP4","FLV","MPEGTS"] | 输出视频的封装格式，支持 MP4、FLV、MPEGTS，默认 MP4。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `metadata_add_tags` | `--metadata-add-tags` | array<object> | 否 | - | - | 可省略，为输出视频新增由 key 和 value 组成的元信息标签；新增标签与保留标签同名时覆盖源文件值；对 MPEGTS 封装格式无效。 |
| `metadata_add_tags[].key` | - | string | 否 | - | - | 标签键。 |
| `metadata_add_tags[].value` | - | string | 否 | - | - | 标签值。 |
| `metadata_keep_tags` | `--metadata-keep-tags` | array<string> | 否 | - | - | 可省略，指定从源视频保留的元信息标签键列表；默认转码会丢弃大部分元信息，例如标题和艺术家；对 MPEGTS 封装格式无效。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video` | `--video` | object | 是 | - | - | 视频转码参数配置。 |
| `video.bitrate_crf` | - | number | 否 | 25 | 最小值: 0；最大值: 51 | 码率 CRF 参数可省略，仅在 video.bitrate_mode=crf 时生效，是 crf 模式主要质量控制器；支持 0 至 51，默认 25；数值越小，画质越高且文件体积越大，0 表示无损。 |
| `video.bitrate_kbps` | - | integer | 是 | 2000 | 最小值: 10；最大值: 50000 | 视频码率目标值，单位 Kbps，支持 10 至 50000，默认 2000；abr 模式下是平均码率目标，cbr 模式下是恒定码率目标，crf 模式下是最大码率限制。 |
| `video.bitrate_mode` | - | string | 是 | "crf" | 枚举: ["crf","abr","cbr"] | 码率控制模式，支持 crf、abr、cbr，默认 crf。crf 模式尽量保持整体视觉质量在 video.bitrate_crf 设定水平，同时确保瞬时码率不超过 video.bitrate_kbps，推荐大多数场景使用；abr 模式使输出整体平均码率接近 video.bitrate_kbps，适用于需要把文件大小控制在特定范围的场景；cbr 模式尝试让视频流每一秒保持在 video.bitrate_kbps 设定码率，画质随复杂度波动而码率稳定，适用于对网络传输稳定性要求极高的流媒体场景。 |
| `video.codec` | - | string | 是 | "h264" | 枚举: ["h264","h265"] | 视频编码格式，支持 h264、h265，默认 h264。 |
| `video.fps` | - | integer | 否 | - | 最小值: 1；最大值: 240 | 目标帧率可省略，支持 1 至 240；未设置时输出完全遵循原视频帧率。设置后会激活 video.fps_mode；vfr 下表示最大帧率，cfr 下表示恒定帧率。 |
| `video.fps_mode` | - | string | 否 | "vfr" | 枚举: ["vfr","cfr"] | 帧率模式可省略，支持 vfr、cfr，默认 vfr。仅在设置 video.fps 后生效；未提供 video.fps 时遵循源帧率并忽略 video.fps_mode。vfr 模式把 video.fps 作为最高帧率，源帧率较低时保留，较高时降低到设定值，避免不必要的帧率过度提升；cfr 模式把 video.fps 作为强制输出帧率，无论源帧率如何都转换为该恒定帧率。 |
| `video.is_hdr_to_sdr` | - | boolean | 否 | true | - | 可省略，控制是否将 HDR 视频转换为 SDR，默认 true；false 时保留 HDR。 |
| `video.scale_height` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | 目标高度，单位 px，可省略，支持 0 至 4320；仅在 video.scale_type=2 时生效，只传宽或高之一时，另一边按比例缩放。 |
| `video.scale_long` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | 目标长边，单位 px，可省略，支持 0 至 4320；仅在 video.scale_type=1 时生效，只传短边或长边之一时，另一边按比例缩放。 |
| `video.scale_mode` | - | integer | 否 | 0 | 枚举: [0,1,2] | 伸缩模式可省略，支持 0、1、2，默认 0，仅在 video.scale_type 为 1 或 2 时生效。0 不上采：源片比目标大时缩小，比目标小时保持原尺寸；1 拉伸上采，强制拉伸到目标宽高，可能导致画面变形；2 补黑边上采，等比缩放到目标框内，不足部分用黑边填充。 |
| `video.scale_short` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | 目标短边，单位 px，可省略，支持 0 至 4320；仅在 video.scale_type=1 时生效，只传短边或长边之一时，另一边按比例缩放。 |
| `video.scale_type` | - | integer | 否 | 0 | 枚举: [0,1,2] | 伸缩限制可省略，支持 0、1、2，默认 0。0 为跟随片源模式，不进行任何缩放，支持最高 8K 分辨率，video.scale_mode、video.scale_width、video.scale_height、video.scale_short、video.scale_long 均无效；1 为长短边限制模式，激活 video.scale_short 和 video.scale_long，可设置长边或短边，另一边按原比例缩放，支持最高 4K 分辨率；2 为宽高限制模式，激活 video.scale_width 和 video.scale_height，可设置宽度或高度，另一边按原比例缩放，支持最高 4K 分辨率。 |
| `video.scale_width` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | 目标宽度，单位 px，可省略，支持 0 至 4320；仅在 video.scale_type=2 时生效，只传宽或高之一时，另一边按比例缩放。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待转码视频的 URL，支持公网 HTTP/HTTPS URL、本地文件路径、视频点播 vod:// 和对象存储 tos:// 四种输入协议；支持 mp4、mov、mkv、flv、ts、avi、wmv 等主流视频格式。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `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_codec` | string | 否 | Cloud 终态 | 视频编码格式，例如 h264 或 h265。 |
| `result.video_url` | string | 否 | Cloud 终态 | 输出视频地址。设置 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 video martencode-video --help
mediakit-cli video martencode-video --schema
```
reference/matte-greenscreen-video.md›
# 视频绿幕抠图
## 能力用途
可对绿幕或纯色背景的视频进行抠图，自动识别并保留主体，最终生成背景透明或纯色背景的视频。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud video matte-greenscreen-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `background_color` | `--background-color` | string | 否 | - | 枚举: ["black","white","green"] | 输出视频的背景颜色；支持 black、white、green，默认为黑色；仅当 format 为 MP4 时生效。 |
| `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。 |
| `format` | `--format` | string | 否 | "WEBM" | 枚举: ["MOV","WEBM","MP4"] | 输出视频的格式；支持 WEBM、MOV、MP4，默认是 WEBM；WEBM 和 MOV 输出透明背景，支持 Alpha 透明通道；MP4 输出纯色背景。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置；支持将处理产物存储至火山引擎视频点播（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、mkv、wmv 等主流视频格式。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud video matte-greenscreen-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 任务结果查询
提交成功后会返回 `task_id`，再执行 `mediakit-cli shared query-task --task-id <task_id>` 查询。
- 当前命令：`mediakit-cli --cloud video matte-greenscreen-video`
- 推荐查询：`mediakit-cli shared query-task --task-id <task_id>`
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud video matte-greenscreen-video --help
mediakit-cli --cloud video matte-greenscreen-video --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local video matte-greenscreen-video`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `format` | `--format` | string | 否 | "MOV" | 枚举: ["MOV"] | 本地仅支持输出带透明通道的 MOV 视频。 |
| `video_url` | `--video-url` | string | 是 | - | - | 输入视频 Url。支持 http://xxx 或 https://xxx 格式。 |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local video matte-greenscreen-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `duration` | number | 否 | Local | 视频时长，单位：秒 |
| `video_url` | string | 否 | Local | 输出视频文件路径或 URL |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local video matte-greenscreen-video --help
mediakit-cli --local video matte-greenscreen-video --schema
```
reference/matte-portrait-video.md›
# 视频人像抠图
## 能力用途
自动识别视频中的人物主体，移除原始背景，并生成背景透明或纯色背景的视频文件，适用于背景替换等后期处理场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video matte-portrait-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `background_color` | `--background-color` | string | 否 | - | 枚举: ["black","white","green"] | 输出视频的背景颜色；black 表示黑色，white 表示白色，green 表示绿色，默认为绿色；仅当 format 为 MP4 时生效。 |
| `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。 |
| `format` | `--format` | string | 否 | "WEBM" | 枚举: ["MOV","WEBM","MP4"] | 输出视频的格式，默认为 WEBM。MP4 输出 MP4 格式和纯色背景，并可选用 background_color 指定背景颜色。MOV 输出 QuickTime Movie 格式和透明背景，支持 Alpha 透明通道。WEBM 输出 WebM 格式和透明背景，支持 Alpha 透明通道。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置；支持将处理产物存储至火山引擎视频点播（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，支持 mp4、flv、ts、avi、mov、mkv、wmv 等主流视频格式；支持公网 HTTP/HTTPS URL、本地文件路径、视频点播 vod:// 和对象存储 tos:// 四种输入协议。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video matte-portrait-video \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 任务结果查询
提交成功后会返回 `task_id`，再执行 `mediakit-cli shared query-task --task-id <task_id>` 查询。
- 当前命令：`mediakit-cli video matte-portrait-video`
- 推荐查询：`mediakit-cli shared query-task --task-id <task_id>`
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video matte-portrait-video --help
mediakit-cli video matte-portrait-video --schema
```
reference/probe-video-metadata.md›
# 视频元信息获取
## 能力用途
探测输入的视频 URL，输出标准化的媒资元信息。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
- Local 仅使用 Local 参数；Cloud-only 或当前未实现字段不得传入。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli --cloud video probe-video-metadata`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待探测的视频 URL。支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。支持公网 HTTP/HTTPS URL、本地上传、火山引擎视频点播和火山引擎对象存储四种输入协议。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --cloud video probe-video-metadata \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.audio_stream_meta` | object / null | 是 | Cloud 终态 | 主音频流元信息。视频不含音频流时返回 null。 |
| `result.audio_stream_meta.bitrate` | number / null | 否 | Cloud 终态 | 音频流码率，单位为 bps。 |
| `result.audio_stream_meta.channels` | number / null | 否 | Cloud 终态 | 音频声道数。 |
| `result.audio_stream_meta.codec` | string / null | 否 | Cloud 终态 | 音频编码格式，例如 aac。 |
| `result.audio_stream_meta.duration` | number / null | 否 | Cloud 终态 | 音频流时长，单位为秒。 |
| `result.audio_stream_meta.sample_rate` | number / null | 否 | Cloud 终态 | 音频采样率，单位为 Hz。 |
| `result.format_meta` | object / null | 是 | Cloud 终态 | 容器层元信息，包含封装格式、码率、时长、大小等。 |
| `result.format_meta.bitrate` | number / null | 否 | Cloud 终态 | 容器码率，单位为 bps。 |
| `result.format_meta.container` | string / null | 否 | Cloud 终态 | 容器格式（封装格式），例如 MP4。 |
| `result.format_meta.duration` | number / null | 否 | Cloud 终态 | 容器声明的时长，单位为秒。 |
| `result.format_meta.md5` | string / null | 否 | Cloud 终态 | 文件 MD5 值（如可获取）。 |
| `result.format_meta.size` | number / null | 否 | Cloud 终态 | 文件大小，单位为 byte。 |
| `result.video_stream_meta` | object / null | 是 | Cloud 终态 | 主视频流元信息。视频不含视频流时返回 null。 |
| `result.video_stream_meta.bitrate` | number / null | 否 | Cloud 终态 | 视频流码率，单位为 bps。 |
| `result.video_stream_meta.codec` | string / null | 否 | Cloud 终态 | 视频编码格式，例如 h264。 |
| `result.video_stream_meta.duration` | number / null | 否 | Cloud 终态 | 视频流原始时长，单位为秒。 |
| `result.video_stream_meta.dynamic_range` | string / null | 否 | Cloud 终态 | 动态范围，可为 HDR 或 SDR。 |
| `result.video_stream_meta.fps` | number / null | 否 | Cloud 终态 | 视频帧率，单位为 fps。 |
| `result.video_stream_meta.height` | number / null | 否 | Cloud 终态 | 视频流显示高度，单位为像素（px）。 |
| `result.video_stream_meta.width` | number / null | 否 | Cloud 终态 | 视频流显示宽度，单位为像素（px）。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --cloud video probe-video-metadata --help
mediakit-cli --cloud video probe-video-metadata --schema
```
## Local
### 命令与生命周期
- 命令：`mediakit-cli --local video probe-video-metadata`
- 生命周期：同步
- 返回方式：直接返回本地结果，不产生 `task_id`。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `video_url` | `--video-url` | string | 是 | - | - | 待探测的视频公网 HTTP/HTTPS URL。 |
### Local CLI 选项
| CLI flag | 必填 | 说明 |
| --- | --- | --- |
| `--output-path` | 否 | 本地文件输出目录或完整输出文件路径；仅在用户明确指定输出位置时传递。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli --local video probe-video-metadata \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `audio_stream_meta` | object / null | 是 | Local | 主音频流元信息。视频不含音频流时返回 null。 |
| `audio_stream_meta.bitrate` | number / null | 否 | Local | 音频流码率，单位为 bps。 |
| `audio_stream_meta.channels` | number / null | 否 | Local | 音频声道数。 |
| `audio_stream_meta.codec` | string / null | 否 | Local | 音频编码格式，例如 aac。 |
| `audio_stream_meta.duration` | number / null | 否 | Local | 音频流时长，单位为秒。 |
| `audio_stream_meta.sample_rate` | number / null | 否 | Local | 音频采样率，单位为 Hz。 |
| `format_meta` | object / null | 是 | Local | 容器层元信息，包含封装格式、码率、时长、大小等。 |
| `format_meta.bitrate` | number / null | 否 | Local | 容器码率，单位为 bps。 |
| `format_meta.container` | string / null | 否 | Local | 容器格式（封装格式），例如 MP4。 |
| `format_meta.duration` | number / null | 否 | Local | 容器声明的时长，单位为秒。 |
| `format_meta.md5` | string / null | 否 | Local | 文件 MD5 值（如可获取）。 |
| `format_meta.size` | number / null | 否 | Local | 文件大小，单位为 byte。 |
| `video_stream_meta` | object / null | 是 | Local | 主视频流元信息。视频不含视频流时返回 null。 |
| `video_stream_meta.bitrate` | number / null | 否 | Local | 视频流码率，单位为 bps。 |
| `video_stream_meta.codec` | string / null | 否 | Local | 视频编码格式，例如 h264。 |
| `video_stream_meta.duration` | number / null | 否 | Local | 视频流原始时长，单位为秒。 |
| `video_stream_meta.dynamic_range` | string / null | 否 | Local | 动态范围，可为 HDR 或 SDR。 |
| `video_stream_meta.fps` | number / null | 否 | Local | 视频帧率，单位为 fps。 |
| `video_stream_meta.height` | number / null | 否 | Local | 视频流显示高度，单位为像素（px）。 |
| `video_stream_meta.width` | number / null | 否 | Local | 视频流显示宽度，单位为像素（px）。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli --local video probe-video-metadata --help
mediakit-cli --local video probe-video-metadata --schema
```
reference/remux-video.md›
# 视频转封装
## 能力用途
视频转封装用于调整视频容器格式，仅修改容器格式，不会重新编解码音视频码流，适用于点播分发适配、流媒体切片打包与多端兼容等场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video remux-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--metadata-keep-tags`）传多个值时用逗号分隔并整体加引号，例如 `--metadata-keep-tags "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--metadata-add-tags`）需传合法 JSON 字符串并整体加单引号，例如 `--metadata-add-tags '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video remux-video \
--video-url <video_url> \
--container-format <container_format>
```
仅使用用户真实输入替换占位符；可选 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 生成、推断或补写。 |
| `container_format` | `--container-format` | string | 是 | "MP4" | 枚举: ["MP4","FLV","MPEGTS"] | 目标封装格式，支持 MP4、FLV、MPEGTS，默认值为 MP4。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶：存储至 VOD 时设为 vod://<您的空间名>；存储至 TOS 时设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要按需授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `metadata_add_tags` | `--metadata-add-tags` | array<object> | 否 | - | - | 可选填写需要为输出视频新增的元信息标签列表，每个标签由 key 和 value 组成；对 MPEGTS 封装格式无效；新增标签与被保留标签同名时，会覆盖源文件的值。 |
| `metadata_add_tags[].key` | - | string | 否 | - | - | 标签键。 |
| `metadata_add_tags[].value` | - | string | 否 | - | - | 标签值。 |
| `metadata_keep_tags` | `--metadata-keep-tags` | array<string> | 否 | - | - | 可选填写需要从源视频保留的元信息标签列表，用于指定需要保留的标签键（Key）；默认情况下转码过程会丢弃大部分元信息（如标题、艺术家等）；对 MPEGTS 封装格式无效。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待处理视频的 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 视频时长，单位为秒。 |
| `result.video_url` | string | 否 | Cloud 终态 | 输出视频地址。未设置 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 video remux-video --help
mediakit-cli video remux-video --schema
```
reference/segment-scenes.md›
# 场景切分
## 能力用途
依据视频的转场和画面内容变化自动切分多个场景片段，输出每个场景片段的时间轴信息与对应的独立视频文件。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video segment-scenes`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 布尔参数（`--enable-clip-fade`、`--return-segment-videos`）只能写成 `--enable-clip-fade=true` 或 `--enable-clip-fade=false`，也可用裸 `--enable-clip-fade`（等价 true）；禁止空格传值 `--enable-clip-fade true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video segment-scenes \
--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 生成、推断或补写。 |
| `enable_clip_fade` | `--enable-clip-fade` | boolean | 否 | false | - | enable_clip_fade 控制是否将检测到的淡入或淡出片段作为独立切片输出。enable_clip_fade 的默认值为 false。enable_clip_fade 为 true 且视频存在明显淡入或淡出过渡时，会将其分割为独立切片。enable_clip_fade 为 false 时不独立输出淡入或淡出片段，而将其视为前后场景的一部分并合并到相邻切片。 |
| `max_duration` | `--max-duration` | number | 否 | - | 最小值: 0 | max_duration 表示单个切片的最大时长，单位为秒。max_duration 的默认值为 30 秒。max_duration 必须大于或等于 min_duration。大于 max_duration 的片段将被强制切分。 |
| `min_duration` | `--min-duration` | number | 否 | - | 最小值: 0 | min_duration 表示单个切片的最小时长，单位为秒。min_duration 的默认值为 3 秒。小于 min_duration 的片段将被合并。min_duration 必须小于或等于 max_duration。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `return_segment_videos` | `--return-segment-videos` | boolean | 否 | true | - | return_segment_videos 的默认值为 true。return_segment_videos 为 true 时生成切片文件，并在 result.segments[].segment_video_url 返回各切片下载链接。return_segment_videos 为 false 时不生成切片文件，仅返回 start_time 和 end_time 切片时间轴，不返回 segment_video_url。false 可用于只需获取场景时间码并由业务侧自行处理切片的场景，可降低任务耗时。 |
| `segment_threshold` | `--segment-threshold` | number | 否 | - | 最小值: 0；最大值: 100 | segment_threshold 是场景切分的敏感度阈值，最小值为 0，必须小于 100。取值越低，算法对场景变化越敏感，切分出的片段越多；取值越高，算法越倾向将微小变化视为同一场景，切分出的片段越少。同时设置 min_duration、max_duration 和 segment_threshold 时，系统采用两阶段逻辑以满足全部约束：第一阶段根据 segment_threshold 和 min_duration 进行切分；第一阶段后如有切片时长超过 max_duration，系统忽略 segment_threshold 再次切分，确保最终时长不超过 max_duration。 |
| `video_url` | `--video-url` | string | 是 | - | - | video_url 是待处理的视频 URL。视频来源支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议。支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式。单个视频时长必须不超过 2 小时。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | result.duration 是输入视频的总时长，单位为秒。 |
| `result.segments` | array<object> | 否 | Cloud 终态 | result.segments 是切片信息列表，每个元素包含切片起止时间等信息。 |
| `result.segments[].end_time` | number | 否 | Cloud 终态 | result.segments[].end_time 是切片的结束时间，单位为秒。 |
| `result.segments[].segment_video_url` | string | 否 | Cloud 终态 | result.segments[].segment_video_url 是切片视频文件的下载地址。切片输出视频为 MP4 格式。仅当 return_segment_videos 为 true（默认）时返回 segment_video_url；return_segment_videos 为 false 时不生成切片文件且不返回 segment_video_url。切片视频文件下载地址的有效期为 24 小时。 |
| `result.segments[].start_time` | number | 否 | Cloud 终态 | result.segments[].start_time 是切片的起始时间，单位为秒。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video segment-scenes --help
mediakit-cli video segment-scenes --schema
```
reference/semantic-segment.md›
# 智能语义切片
## 能力用途
综合分析视频的画面、语音和叙事结构，通过镜头切换、语音停顿检测等策略，在保证语义完整、避免将单句从中间切断的前提下，将长视频智能地切分为多个独立的素材片段。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video semantic-segment`
- 生命周期：异步
- 返回方式：返回 `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 生成、推断或补写。 |
| `max_duration` | `--max-duration` | number | 否 | 30 | 最小值: 1 | 单个切片的目标最大时长，单位为秒；默认值为 30，最小值为 1。超过该时长的片段将触发强制切分，保证片段不会过长；必须大于或等于 min_duration。 |
| `max_shift_tolerance` | `--max-shift-tolerance` | number | 否 | 0 | 最小值: 0 | 切点偏移容忍度，单位为秒；默认值为 0，最小值为 0。当该值大于 0 时，会在切点前后该范围内寻找更贴近语义的位置，如句末、停顿。该值越大，切点越贴合语义，但切片实际时长相对 min_duration 或 max_duration 的抖动也越大；必须小于或等于 min_duration。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的对象存储（TOS）桶，可设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要授权 AI MediaKit 将文件写入您的 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `min_duration` | `--min-duration` | number | 否 | 3 | 最小值: 1 | 单个切片的目标最小时长，单位为秒；默认值为 3，最小值为 1。小于该时长的片段会与相邻切片合并，前提是合并后不超过 max_duration，以避免产生过短碎片；必须小于或等于 max_duration。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video_url` | `--video-url` | string | 是 | - | 格式: "^(http\|https\|mediakit\|vod\|tos)://" | 待处理的视频 URL；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；单个视频时长不得超过 3 小时。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video semantic-segment \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输入视频的总时长，单位为秒。 |
| `result.result_url` | string | 否 | Cloud 终态 | 语义切片结果文件地址；未设置 media_output_destination 时，返回有效期为 24 小时的 HTTPS 临时下载链接；设置 media_output_destination 后，返回 tos://<桶名>/<对象Key> 格式的存储地址。文件为 gzip 压缩后的 JSON，包含 source、duration_ms、duration、has_audio、segment_count、segments 等字段。 |
| `result.segment_count` | integer | 否 | Cloud 终态 | 最终切分出的语义片段数量。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video semantic-segment --help
mediakit-cli video semantic-segment --schema
```
reference/transcode-video.md›
# 视频转码
## 能力用途
视频转码将视频码流转换为另一视频码流，可涉及编码格式、分辨率、码率、I 帧间隔和封装格式转换，用于适应不同业务场景、播放终端和网络环境。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video transcode-video`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--metadata-keep-tags`）传多个值时用逗号分隔并整体加引号，例如 `--metadata-keep-tags "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--audio`、`--metadata-add-tags`、`--video`）需传合法 JSON 字符串并整体加单引号，例如 `--audio '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video transcode-video \
--video-url <video_url> \
--container-format <container_format> \
--video <video>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `audio` | `--audio` | object | 否 | - | - | 不传 audio 时，音频使用 aac 编码，其他参数跟随源文件。 |
| `audio.bitrate_kbps` | - | integer | 是 | 128 | 最小值: 10；最大值: 500 | 音频码率单位 Kbps，范围 [10, 500]，默认 128；不设置时跟随原始音频码率。 |
| `audio.bitrate_mode` | - | string | 是 | "cbr" | 枚举: ["cbr","cae"] | cae 仅在 audio.codec=aac 时支持，按内容复杂度调整瞬时码率并使平均码率接近 bitrate_kbps。cbr 是默认恒定码率模式，仅在 video.codec=h264 时支持，用于带宽稳定性要求高的流式传输。 |
| `audio.channels` | - | integer | 否 | 2 | 枚举: [1,2] | 音频声道数支持 1（单声道）和 2（双声道），默认是 2。 |
| `audio.codec` | - | string | 是 | "aac" | 枚举: ["aac"] | 音频编码当前仅支持 aac，默认也是 aac。 |
| `audio.sample_rate` | - | integer | 是 | 44100 | 枚举: [8000,11025,12000,16000,22050,24000,32000,44100,48000,64000,88200,96000] | aac 支持采样率 8000、11025、12000、16000、22050、24000、32000、44100、48000、64000、88200、96000 Hz，默认 44100 Hz。 |
| `audio.volume_integrated_loudness` | - | number | 否 | -12 | 最小值: -70；最大值: -5 | 响度值设置，用于在音量均衡模式下调整音频的整体响度水平。取值范围为 [-70, -5]，默认值为 -12。当 Method 参数取值为 2Pass时，该参数必填。 |
| `audio.volume_loudness_range` | - | number | 否 | 7 | 最小值: 1；最大值: 20 | 响度范围单位 LU，范围 [1, 20]，默认 7；volume_method=2Pass 时生效。 |
| `audio.volume_method` | - | string | 否 | - | 枚举: ["2Pass"] | volume_method=2Pass 可启用两阶段响度分析与处理，使三个响度参数生效；不设置时不处理音量。 |
| `audio.volume_true_peak` | - | number | 否 | 0 | 最小值: -9；最大值: 0 | 音量峰值，用于在音量均衡模式下设置音频的最大峰值。取值范围为 [-9, 0]，默认值为 0。当 Method 参数取值为 2Pass时，该参数必填。 |
| `callback_args` | `--callback-args` | string | 否 | - | - | 自定义回调参数。任务完成时，您提供的内容会通过事件回调原样返回，便于关联业务；字段长度最大为 512 字节。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `callback_url` | `--callback-url` | string | 否 | - | - | 用于接收该任务结果回调的 URL 地址。提供此参数时，其优先级高于全局回调地址；地址必须以 http:// 或 https:// 开头。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `client_token` | `--client-token` | string | 否 | - | - | 用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `container_format` | `--container-format` | string | 是 | "MP4" | 枚举: ["MP4","FLV","MPEGTS"] | 输出封装格式支持 MP4、FLV、MPEGTS，默认是 MP4。 |
| `media_output_destination` | `--media-output-destination` | string | 否 | - | - | 指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的对象存储（TOS）桶，可设为 tos://<您的桶名>。设置后，任务结果中的 url 相关字段将返回 tos:// 格式的资源地址，不再返回临时下载地址。首次使用前，需要授权 AI MediaKit 将文件写入您的 TOS 桶。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `metadata_add_tags` | `--metadata-add-tags` | array<object> | 否 | - | - | 新增元信息标签与保留标签同名时，新设置覆盖源文件值。metadata_add_tags 对 MPEGTS 封装格式无效。 |
| `metadata_add_tags[].key` | - | string | 否 | - | - | 标签键。 |
| `metadata_add_tags[].value` | - | string | 否 | - | - | 标签值。 |
| `metadata_keep_tags` | `--metadata-keep-tags` | array<string> | 否 | - | - | 可指定从源视频保留的元信息标签键；默认转码会丢弃大部分元信息。metadata_keep_tags 对 MPEGTS 封装格式无效。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `video` | `--video` | object | 是 | - | - | 视频参数，必填 |
| `video.bitrate_crf` | - | number | 否 | 25 | 最小值: 0；最大值: 51 | bitrate_crf 仅在 bitrate_mode=crf 时生效；值越小画质越高、体积越大，0 表示无损。bitrate_crf 范围 [0, 51]。 |
| `video.bitrate_kbps` | - | integer | 是 | 2000 | 最小值: 10；最大值: 50000 | video.bitrate_kbps 在 crf、abr、cbr 模式下分别表示最大码率限制、平均码率目标、恒定码率目标。 |
| `video.bitrate_mode` | - | string | 是 | "crf" | 枚举: ["crf","abr","cbr"] | crf 推荐用于大多数场景，尽量保持 bitrate_crf 指定的视觉质量，并以 bitrate_kbps 限制瞬时码率。abr 调整码率使整体平均码率接近 bitrate_kbps，适合将文件大小控制在特定范围。cbr 尝试让视频流每秒严格保持 bitrate_kbps 设定码率，适合要求网络传输稳定的流媒体场景。 |
| `video.codec` | - | string | 是 | "h264" | 枚举: ["h264","h265"] | 视频编码格式支持 h264 和 h265，默认是 h264。 |
| `video.fps` | - | integer | 否 | - | 最小值: 1；最大值: 240 | fps 范围 [1, 240]；vfr 下是最大帧率，cfr 下是恒定帧率。 |
| `video.fps_mode` | - | string | 否 | "vfr" | 枚举: ["vfr","cfr"] | 只有设置 fps 后 fps_mode 才生效；未提供 fps 时遵循原视频帧率并忽略 fps_mode。cfr 将 fps 作为强制恒定输出帧率。vfr 将 fps 作为最高帧率；源帧率较低时保留，较高时降低到 fps。 |
| `video.is_hdr_to_sdr` | - | boolean | 否 | true | - | true 将 HDR 转换为 SDR；false 保留 HDR。 |
| `video.scale_height` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | scale_height 单位为 px，范围 [0, 4320]，仅在 scale_type=2 时生效；只传宽或高之一时另一边按比例缩放。 |
| `video.scale_long` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | scale_long 单位为 px，范围 [0, 4320]，仅在 scale_type=1 时生效；只传短边或长边之一时另一边按比例缩放。 |
| `video.scale_mode` | - | integer | 否 | 0 | 枚举: [0,1,2] | scale_mode 仅在 scale_type 为 1 或 2 时生效。0 不上采：源片大于目标时缩小，小于目标时保持原尺寸。1 强制拉伸到目标宽高，可能导致画面变形。2 等比缩放到目标框内并用黑边填充不足部分。 |
| `video.scale_short` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | scale_short 单位为 px，范围 [0, 4320]，仅在 scale_type=1 时生效；只传短边或长边之一时另一边按比例缩放。 |
| `video.scale_type` | - | integer | 否 | 0 | 枚举: [0,1,2] | scale_type=0 跟随片源且不缩放，相关尺寸参数无效，最高支持 8K。scale_type=1 激活 scale_short 和 scale_long，另一边按原比例缩放，最高支持 4K。scale_type=2 激活 scale_width 和 scale_height，另一边按原比例缩放，最高支持 4K。视频缩放模式默认是 0。 |
| `video.scale_width` | - | integer | 否 | - | 最小值: 0；最大值: 4320 | scale_width 单位为 px，范围 [0, 4320]，仅在 scale_type=2 时生效；只传宽或高之一时另一边按比例缩放。 |
| `video_url` | `--video-url` | string | 是 | - | - | 待转码视频支持 mp4、mov、mkv、flv、ts、avi、wmv 等主流视频格式；支持公网 HTTP/HTTPS URL、本地文件路径、vod:// 和 tos:// 四种来源协议。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `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_codec` | string | 否 | Cloud 终态 | 转码后视频的编码格式。 |
| `result.video_url` | string | 否 | Cloud 终态 | 未设置 media_output_destination 时返回有效期 24 小时的 HTTPS 临时下载链接；设置后返回 vod:// 或 tos:// 存储地址。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video transcode-video --help
mediakit-cli video transcode-video --schema
```
reference/video-ocr.md›
# 视频识别字幕（OCR）
## 能力用途
用于视频字幕识别（OCR），识别输入视频画面中的字幕信息，输出带时间戳的结构化文本数据。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video video-ocr`
- 生命周期：异步
- 返回方式：返回 `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 生成、推断或补写。 |
| `mode` | `--mode` | string | 否 | "Subtitle" | 枚举: ["Subtitle","Detailed"] | 工作模式。支持 Subtitle 或 Detailed，默认为 Subtitle。Subtitle 模式仅识别视频画面中符合字幕特征的文本，适用于快速提取视频对白、生成字幕稿等场景；Detailed 模式识别画面中更详细的文本信息，包括字幕、水印、台标、标题等；Detailed 模式的返回结果会额外包含 text_label 和 text_location 字段。 |
| `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 等主流视频格式；输入视频分辨率支持 240p 到 4k，单文件视频时长不得超过 10 分钟。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video video-ocr \
--video-url <video_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `request_id` | string | 否 | Cloud | 请求标识；仅在后端返回时出现。 |
| `task_id` | string | 是 | Cloud | 异步任务的唯一标识，用于查询任务状态并获取最终结果。 |
| `task_type` | string | 否 | Cloud | 任务类型；仅在后端实际返回非空值时出现。 |
| `result.duration` | number | 否 | Cloud 终态 | 输入视频总时长，单位为秒。 |
| `result.subtitles` | array<object> | 否 | Cloud 终态 | 字幕片段列表，每个元素包含字幕文本和时间戳。 |
| `result.subtitles[].end_time` | number | 否 | Cloud 终态 | 结束时间（秒） |
| `result.subtitles[].start_time` | number | 否 | Cloud 终态 | 起始时间（秒） |
| `result.subtitles[].subtitle_text` | string | 否 | Cloud 终态 | 识别文本 |
| `result.subtitles[].text_label` | string | 否 | Cloud 终态 | 文本类别标签（仅 Detailed 模式返回）。Subtitle: 字幕文本；Others: 画面中的其他文字（如水印、台标、贴片等非字幕内容） |
| `result.subtitles[].text_location` | object | 否 | Cloud 终态 | 文本在画面中的像素坐标区域（仅 Detailed 模式返回）。 |
| `result.subtitles[].text_location.bottom_right_x` | integer | 否 | Cloud 终态 | 文本框右下角横坐标，单位 px。 |
| `result.subtitles[].text_location.bottom_right_y` | integer | 否 | Cloud 终态 | 文本框右下角纵坐标，单位 px。 |
| `result.subtitles[].text_location.top_left_x` | integer | 否 | Cloud 终态 | 文本框左上角横坐标，单位 px。 |
| `result.subtitles[].text_location.top_left_y` | integer | 否 | Cloud 终态 | 文本框左上角纵坐标，单位 px。 |
Cloud 调用成功后读取 `task_id`，再查询终态结果：
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli shared query-task --task-id <task_id> --poll-complete
```
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video video-ocr --help
mediakit-cli video video-ocr --schema
```
reference/video-understand-router.md›
# 视频理解智能策略
## 能力用途
基于视觉大模型，对输入的视频 URL 列表进行通用视频内容分析，输出视频级别的结构化理解结果，适用于内容审核、视频检索、标签生成等场景。
## 参数填写规则
- 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli video video-understand-router`
- 生命周期：异步
- 返回方式：返回 `task_id`，再查询终态结果。
### 使用指南
- 数组参数（`--prefer-endpoints`、`--prefer-models`、`--video-urls`）传多个值时用逗号分隔并整体加引号，例如 `--prefer-endpoints "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
- 对象或对象数组参数（`--manual-option`）需传合法 JSON 字符串并整体加单引号，例如 `--manual-option '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli video video-understand-router \
--video-urls <video_urls_1>,<video_urls_2> \
--prompt <prompt>
```
仅使用用户真实输入替换占位符；可选 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 可打印字符。 默认不传。用户明确指定时原样使用；用户明确要求重试时，同一逻辑请求的重试链必须复用同一 token。已有 token 时必须复用原值；此前请求未带 token 时，可从本次重试开始创建一次并持续复用，但该 token 不对此前请求提供追溯幂等。业务参数变化视为新请求，不得复用旧 token。不得为每次尝试生成不同值。CLI/MCP runtime 不判断重试意图，也不自动生成 token。 |
| `level` | `--level` | string | 否 | "Economy" | 枚举: ["Economy","Balanced","Quality"] | level 是分析档位，决定任务的默认抽帧策略与模型选择，以在成本、速度和质量之间取得平衡；支持 Economy、Balanced、Quality，默认 Economy。Economy 是速度优先的经济档位，适合大批量、对结果详细程度要求较低的内容标注；Balanced 是速度与质量兼顾的均衡档位，适合常规内容审核与检索场景；Quality 是结果优先的质量档位，适合需要更精细语义理解的场景。 |
| `manual_option` | `--manual-option` | object | 否 | - | - | manual_option 是手动模式相关参数；未传 manual_option 时表示完全使用 level 档位策略，不进行手动覆盖。 |
| `manual_option.fps` | - | number | 否 | 1 | 最小值: 0.2；最大值: 5 | manual_option.fps 是抽帧帧率，设置后会按照指定帧率进行均匀抽帧；最小 0.2，最大 5.0，默认 1.0。 |
| `manual_option.max_snapshot_number` | - | integer | 否 | 0 | 最大值: 1000 | manual_option.max_snapshot_number 是最大抽帧帧数，最小 0，最大 1000，默认 0；显式设置时会覆盖档位策略；设为 0 时由 level 档位决定截图数量。 |
| `manual_option.need_audio` | - | boolean | 否 | false | - | manual_option.need_audio 表示是否开启或关闭音频分析，支持 true 和 false，默认 false。为 true 时开启音频分析，系统将选用支持音视频多模态的模型，并分析音频内容。为 false 时关闭音频分析，仅分析视频画面；即使 manual_option.need_audio 为 false 或未提供，如果 prompt 中包含“声音”、“音乐”等音频相关关键词，也可能自动触发音频分析。 |
| `prefer_endpoints` | `--prefer-endpoints` | array<string> | 否 | - | 最少项数: 1；最多项数: 10 | prefer_endpoints 是优先使用的推理接入点 ID（Endpoint ID）列表，最多 10 个；系统将从 prefer_endpoints 指定的推理接入点中结合策略选择最终模型；prefer_endpoints 的优先级高于 prefer_models。 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
| `prefer_models` | `--prefer-models` | array<string> | 否 | - | 最少项数: 1；最多项数: 10 | prefer_models 是优先使用的模型 ID（Model ID）列表，最多 10 个；系统将从 prefer_models 指定的模型中结合策略选择最终模型。 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
| `prompt` | `--prompt` | string | 是 | - | 最短长度: 1 | prompt 是用于指导大模型对视频内容进行分析的自然语言描述，最小长度为 1。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID；不传时默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以按队列对应的项目进行分账。队列可创建和管理，系统会自动分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `scene` | `--scene` | string | 否 | - | 枚举: ["editing"] | scene 是分析场景，用于系统优化处理策略；指定 scene 后，系统会自动决策使用该场景的最佳策略；不传时表示通用场景。editing 表示创作剪辑场景，模型会侧重于理解并输出带有精确时间戳的详细分镜信息，适用于分镜理解、智能剪辑、二次 AIGC 创作等下游任务。 |
| `video_urls` | `--video-urls` | array<string> | 是 | - | 最少项数: 1；最多项数: 10 | video_urls 是待处理的视频 URL 列表，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎视频点播 vod:// 和火山引擎对象存储 tos:// 四种输入协议；支持 mp4、flv、ts、avi、mov、wmv、mkv 等主流视频格式；单次任务最多支持传入 10 个视频文件。 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
### 任务结果查询
提交成功后会返回 `task_id`，再执行 `mediakit-cli shared query-task --task-id <task_id>` 查询。
- 当前命令：`mediakit-cli video video-understand-router`
- 推荐查询：`mediakit-cli shared query-task --task-id <task_id>`
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli video video-understand-router --help
mediakit-cli video video-understand-router --schema
```
SKILL.md›
---
name: byted-mediakit-video
version: "0.2.1"
license: "MIT"
description: "面向视频文件的智能处理、媒资理解、画质治理与画质检测、抽帧、隐私保护、语音转字幕、字幕提取、字幕擦除、水印处理、精彩片段与高光拆条分析生成、剧情结构化与剧本整理、场景与语义分段、画面文字识别、视频转码转封装及抠像换脸等目标。若对象和目标族已明确属于视频增强、视频分析理解、视频内容结构化、从视频提取字幕、语音转字幕、视频字幕识别或擦除、视频隐私脱敏、视频媒资探测或分发适配，但具体能力不确定，可先加载本 Skill 探索。"
permissions:
- shell
metadata:
requires:
bins: ["mediakit-cli"]
cliHelp: "mediakit-cli video --help"
product: mediakit-cli/skills
domain: video
capability_count: 30
---
# video MediaKit Skill
## 使用规则
1. 先读取 `../byted-mediakit-shared/SKILL.md`，执行统一前置检查；该 Skill 缺失时停止并提示安装。
2. 只从下表选择 `video` 域工具；相似能力按各工具“能力描述”和参数边界区分。
3. 执行前按需读取对应 reference；参数与结果说明来自同一份已审核文案，完整机器合同以当前 CLI `--schema` 为准。
4. 缺少必填参数、鉴权环境变量或真实输入资源时，向用户索取；通用可选字段只能透传用户明确提供的值，其他可选字段可由明确意图准确确定，但不得伪造。
5. 执行时设置 `MEDIAKIT_SURFACE=skill`，指定调用来源是 Skill。
6. 执行时把 `MEDIAKIT_RUNTIME` 设置为当前 Agent 宿主，避免 CLI 无法可靠识别父级 Agent。
## 澄清与跨域路由
若只说有视频而未说明业务目标，应先澄清。明确要把字幕或图片叠加压制到成片、或做裁剪、拼接、混音、合流、调速、转场、画面旋转翻转、视频滤镜或多视频拼画面的成片编辑诉求应路由到 editing；单张图片处理应路由到 image；音频转码、人声分离或语音端点检测应路由到 audio。
## 工具列表
| 工具 | 说明 | 支持模式 | 命令 | 参考 |
| --- | --- | --- | --- | --- |
| add-video-invisible-watermark | 用于视频暗水印添加。在不影响视频画面视觉质量与完整性的前提下，将一串数字信息隐藏式地嵌入视频文件中。适用于视频版权保护、内容泄露溯源、文件真实性校验等场景。 | Cloud | `mediakit-cli video add-video-invisible-watermark` | [reference/add-video-invisible-watermark.md](reference/add-video-invisible-watermark.md) |
| analyze-video-highlights | 支持短剧 Miniseries 和小游戏 Game 两种分析模型，用于高光片段提取，并输出精准时间戳、高光打分、OCR 文本和画面描述，供二次开发或内容分析。 | Cloud | `mediakit-cli video analyze-video-highlights` | [reference/analyze-video-highlights.md](reference/analyze-video-highlights.md) |
| analyze-video-storyline | 用于剧情故事线分析，基于大模型视频理解分析单个或多个长视频并生成结构化剧情数据。分析结果包含两部分：按时间顺序排列的剧情片段，以及基于视频片段整理和归纳出的高光故事线。 | Cloud | `mediakit-cli video analyze-video-storyline` | [reference/analyze-video-storyline.md](reference/analyze-video-storyline.md) |
| asr-subtitles | 从视频或音频的语音中识别并提取带时间戳的字幕文本；适用于提取视频字幕、语音转字幕、听写对白等诉求。识别对象是音轨中的语音内容，不是画面上已烧录的硬字幕。 | Cloud | `mediakit-cli video asr-subtitles` | [reference/asr-subtitles.md](reference/asr-subtitles.md) |
| assess-video-quality | 用于视频画质检测。 | Cloud | `mediakit-cli video assess-video-quality` | [reference/assess-video-quality.md](reference/assess-video-quality.md) |
| drama-recap | 基于已完成的剧本还原任务，可使用自定义解说词或由 AI 自动生成解说词，生成带 AI 配音与解说字幕的营销或解说视频；可配置音色、字幕样式与原文字幕擦除。 | Cloud | `mediakit-cli video drama-recap` | [reference/drama-recap.md](reference/drama-recap.md) |
| drama-recap-vertical | 基于输入短剧剧集的角色与剧情故事线理解，自动提取高光片段并生成全新解说视频；支持文字解说（原片高光混剪 + 屏幕文字）与旁白解说（原片高光混剪 + AI 语音 + BGM），并可套用短剧三要素视觉模板。 | Cloud | `mediakit-cli video drama-recap-vertical` | [reference/drama-recap-vertical.md](reference/drama-recap-vertical.md) |
| drama-script | 基于大模型视频理解能力，将短剧视频转化为结构化剧本文本，识别并提取场景、人物、对话和情节等核心元素。 | Cloud | `mediakit-cli video drama-script` | [reference/drama-script.md](reference/drama-script.md) |
| enhance-video | 用于视频画质增强。利用 AI 算法对输入视频进行分析，并智能执行包括但不限于视频去噪、色彩增强、清晰度提升、瑕疵修复和超分辨率的一系列优化操作。提供 standard 和 professional 两种版本：standard 兼顾处理速度与视频画质，内置高频使用的 10 余种增强算法，适用于视频分发场景的画质增强；professional 提供极致画质增强，内置 30 余种深度 AI 增强算法，适用于影视级视频制作。不同版本会影响增强算法的强度、适用场景与计费。 | Cloud | `mediakit-cli video enhance-video` | [reference/enhance-video.md](reference/enhance-video.md) |
| enhance-video-fast | 集成轻量级超分与智能画质增强，采用速度优先策略，高效兼顾处理效率与画面效果，尤其适用于处理时延敏感的业务场景。 | Cloud | `mediakit-cli video enhance-video-fast` | [reference/enhance-video-fast.md](reference/enhance-video-fast.md) |
| enhance-video-generative | 基于 Diffusion 扩散大模型技术提供生成式视频增强与修复，通过深度语义理解，智能补全和生成符合视频内容的真实细节，可修复视频在压缩或老化过程中损失的像素，最终产出自然、高保真的视频画面。 | Cloud | `mediakit-cli video enhance-video-generative` | [reference/enhance-video-generative.md](reference/enhance-video-generative.md) |
| erase-video-subtitle | 智能检测并擦除视频画面中已有的硬字幕，保留原始背景。<br>支持格式：主流视频格式如mp4、flv、ts、avi、mov、wmv、mkv。 | Cloud | `mediakit-cli video erase-video-subtitle` | [reference/erase-video-subtitle.md](reference/erase-video-subtitle.md) |
| erase-video-subtitle-pro | 用于字幕擦除（精细化版），对视频字幕进行高质量无痕擦除，并最大程度还原视频画面。 | Cloud | `mediakit-cli video erase-video-subtitle-pro` | [reference/erase-video-subtitle-pro.md](reference/erase-video-subtitle-pro.md) |
| extract-frames | 从视频中抽取截图，截图结果支持用于视频封面、预览图、雪碧图或其他视频理解任务的输入。 | Cloud | `mediakit-cli video extract-frames` | [reference/extract-frames.md](reference/extract-frames.md) |
| extract-video-invisible-watermark | 从已嵌入暗水印的视频中解析并还原隐藏的数字信息；如果同一视频被多次嵌入暗水印，也能够提取出所有水印信息。 | Cloud | `mediakit-cli video extract-video-invisible-watermark` | [reference/extract-video-invisible-watermark.md](reference/extract-video-invisible-watermark.md) |
| face-blur-video | 视频人脸打码可自动精准识别视频画面中的人脸区域，并对所有人脸进行模糊或马赛克处理，适用于需要保护人物五官隐私的场景。 | Cloud | `mediakit-cli video face-blur-video` | [reference/face-blur-video.md](reference/face-blur-video.md) |
| face-swap-video | 将用户提供的目标人脸融合替换到视频中的人物上，输出高质量换脸视频，主要适用于生成式视频脱敏需要换脸的场景。 | Cloud | `mediakit-cli video face-swap-video` | [reference/face-swap-video.md](reference/face-swap-video.md) |
| generate-highlights-microdrama | 可用于短剧高光智剪，基于输入剧集的角色和剧情故事线理解提取高光片段，并按时长、产出个数、顺剪或跳剪等要求生成高光混剪、单集预告等视频。 | Cloud | `mediakit-cli video generate-highlights-microdrama` | [reference/generate-highlights-microdrama.md](reference/generate-highlights-microdrama.md) |
| generate-highlights-minigame | 支持识别小游戏录屏视频中的核心玩法与高光事件，例如连击、通关、极限操作，并快速生成用于买量推广的视频素材。可选提供游戏名称、玩法描述和高光定义，辅助更精准地识别精彩内容。 | Cloud | `mediakit-cli video generate-highlights-minigame` | [reference/generate-highlights-minigame.md](reference/generate-highlights-minigame.md) |
| generate-highlights-movie | 支持面向电影、电视剧等长视频内容，按剧情故事线识别高光并拆分成多段指定时长的高光片段，用于影视合集分发的短视频素材；算法会识别并去除景色铺垫、缓慢运镜、片头片尾曲等低密度信息；每段拆条带有高光前置开场与结尾钩子设计。 | Cloud | `mediakit-cli video generate-highlights-movie` | [reference/generate-highlights-movie.md](reference/generate-highlights-movie.md) |
| martencode-video | 极智超清在转码时智能分析视频的场景、动作、内容和纹理，选择最优编码参数，以相对较低码率输出主观画质更优的视频，降低带宽成本并改善用户视觉体验。 | Cloud | `mediakit-cli video martencode-video` | [reference/martencode-video.md](reference/martencode-video.md) |
| matte-greenscreen-video | 可对绿幕或纯色背景的视频进行抠图，自动识别并保留主体，最终生成背景透明或纯色背景的视频。 | Cloud / Local | `mediakit-cli video matte-greenscreen-video` | [reference/matte-greenscreen-video.md](reference/matte-greenscreen-video.md) |
| matte-portrait-video | 自动识别视频中的人物主体，移除原始背景，并生成背景透明或纯色背景的视频文件，适用于背景替换等后期处理场景。 | Cloud | `mediakit-cli video matte-portrait-video` | [reference/matte-portrait-video.md](reference/matte-portrait-video.md) |
| probe-video-metadata | 探测输入的视频 URL，输出标准化的媒资元信息。 | Cloud / Local | `mediakit-cli video probe-video-metadata` | [reference/probe-video-metadata.md](reference/probe-video-metadata.md) |
| remux-video | 视频转封装用于调整视频容器格式，仅修改容器格式，不会重新编解码音视频码流，适用于点播分发适配、流媒体切片打包与多端兼容等场景。 | Cloud | `mediakit-cli video remux-video` | [reference/remux-video.md](reference/remux-video.md) |
| segment-scenes | 依据视频的转场和画面内容变化自动切分多个场景片段，输出每个场景片段的时间轴信息与对应的独立视频文件。 | Cloud | `mediakit-cli video segment-scenes` | [reference/segment-scenes.md](reference/segment-scenes.md) |
| semantic-segment | 综合分析视频的画面、语音和叙事结构，通过镜头切换、语音停顿检测等策略，在保证语义完整、避免将单句从中间切断的前提下，将长视频智能地切分为多个独立的素材片段。 | Cloud | `mediakit-cli video semantic-segment` | [reference/semantic-segment.md](reference/semantic-segment.md) |
| transcode-video | 视频转码将视频码流转换为另一视频码流，可涉及编码格式、分辨率、码率、I 帧间隔和封装格式转换，用于适应不同业务场景、播放终端和网络环境。 | Cloud | `mediakit-cli video transcode-video` | [reference/transcode-video.md](reference/transcode-video.md) |
| video-ocr | 用于视频字幕识别（OCR），识别输入视频画面中的字幕信息，输出带时间戳的结构化文本数据。 | Cloud | `mediakit-cli video video-ocr` | [reference/video-ocr.md](reference/video-ocr.md) |
| video-understand-router | 基于视觉大模型，对输入的视频 URL 列表进行通用视频内容分析，输出视频级别的结构化理解结果，适用于内容审核、视频检索、标签生成等场景。 | Cloud | `mediakit-cli video video-understand-router` | [reference/video-understand-router.md](reference/video-understand-router.md) |