AI MediaKit 的智能语义切片（专业版）工具，面向长视频理解、素材拆条和二次剪辑场景，在基础版的语义切分能力之上进一步结合镜头边界、场景语义、ASR/OCR 文本与时长约束，将长视频切成语义完整、时长合适的片段。相比[智能语义切片（基础版）](https://docs.volcengine.com/docs/6448/2558632)，专业版内置**短剧、影视剧、小游戏**三套行业切片策略并支持**自定义策略**，且直接在响应中返回详细的切片、镜头、场景与分句结果。本篇开发指南将引导您： * 理解智能语义切片（专业版）的工作方式与内置切片策略。 * 快速从一个视频中获取语义切片结果。 * 学习如何按业务场景选择切片策略、控制切片时长范围，并按需返回镜头、场景与分句明细。 ## 基础版与专业版对比 AI MediaKit 针对智能语义切片提供基础版和专业版两个版本，以满足不同场景下的使用需求。下表详细对比了两个版本的主要区别： |**对比项** |**智能语义切片（基础版）** |**智能语义切片（专业版）** | |---|---|---| |核心功能 |基于通用模型进行语义切分，综合分析画面、语音和叙事结构。 |基于行业模型进行精细化切分，支持镜头、场景、分句等多维度分析。 | |适用场景 |适用于对视频进行快速、初步的语义拆条。 |* 适用于短剧、影视、游戏等特定行业的精细化拆条。

* 需要获取镜头、场景、分句等结构化信息用于深度分析。

* 希望直接生成并获取切片视频文件。 | |切片策略 |通用策略，通过 `max_shift_tolerance` 参数微调切点，保证语义完整性。 |提供 `short_drama`, `movie_series`, `mini_game` 三种内置行业策略，及可灵活配置的 `custom` 策略。 | |结果获取 |任务完成后，需通过 `result_url` 下载 Gzip 压缩的 JSON 文件。 |任务完成后，所有结果直接在查询任务 API 的响应中返回，无需下载。 | |结果内容 |仅返回切片的时间轴列表（`segments`）。 |始终返回切片列表（`segments`），并可按需额外返回镜头（`shots`）、场景（`scenes`）、分句（`sentences`）的详细列表。 | |生成切片视频 |不支持。 |支持。通过设置 `return_segment_videos: true`，可在结果中直接获取每个切片的视频文件链接。 | |计费价格 |0.03 元/分钟 |0.06 元/分钟 | ## 快速体验：获取视频语义切片结果本节将通过一个具体的示例，演示如何为一个视频文件进行专业版语义切分，并获取所有语义片段的信息。 ### 准备工作 1. **获取访问凭证**：在开始之前，访问 AI MediaKit 控制台 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)，创建并获取 **MediaKit API Key**（用于媒体处理功能鉴权）。 2. **准备视频文件**：准备一个待处理的视频文件，并将其上传至公网可访问的服务器或[视频点播服务](https://www.volcengine.com/docs/4/2834?lang=zh)中，以获取可供 API 调用的 URL。 ### 操作流程智能语义切片（专业版）是一个异步任务，整体流程如下： 1. 成功调用 `POST /api/v1/tools/semantic-segment-pro` 提交任务后，您将获得一个唯一的 `task_id`。 2. 您可以轮询[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532)，直到任务状态 `status` 变为 `completed`；或者使用[事件回调](https://docs.volcengine.com/docs/6448/2288701)自动接收任务状态变化。 3. 任务完成后，直接解析响应中的 `result` 字段：`segments` 数组始终返回，包含所有语义片段的时间轴信息；`shots`/`scenes`/`sentences` 等明细字段按 `include_detail_types` 与所选策略按需返回。 #### 第 1 步：提交任务调用[提交智能语义切片（专业版）任务 API](https://docs.volcengine.com/docs/6448/2693717)。您可以直接复制以下 cURL 命令，向 API 提交一个基本的专业版语义切片任务。专业版必须通过 `strategy` 指定切片策略，本示例使用短剧策略 `short_drama`。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment-pro' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_long_video.mp4", "strategy": "short_drama" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 video_url 的值替换为您自己准备的视频文件 URL。

strategy 为必填参数，请根据视频内容选择合适的切片策略（详见选择切片策略）。

请求成功后，您会收到如下包含 `task_id` 的响应，请保存此 ID 用于后续查询。 ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-pro-123456789", "request_id": "20260807130000ABCDEFG12345" } ``` #### 第 2 步：获取结果由于视频处理需要时间，您需要通过轮询[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532) 来获取最终结果，直到任务状态变为 `completed`。 ```Bash curl -X GET 'https://mediakit.cn-beijing.volces.com/api/v1/tasks/{task_id}' \ -H 'Authorization: Bearer {Your_API_Key}' ```

说明

将 URL 末尾的 {task_id} 替换为第 1 步返回的任务 ID。

当任务成功完成后，您将收到如下响应。切片结果直接在 `result` 字段中返回，`segments` 数组始终包含所有语义片段。 ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-pro-123456789", "status": "completed", "result": { "duration": 185.5, "segment_count": 2, "segments": [ { "index": 0, "start_ms": 0, "end_ms": 12500, "start": "00:00:00.000", "end": "00:00:12.500", "shot_ids": [0, 1], "text": "切片文本" }, { "index": 1, "start_ms": 12500, "end_ms": 27800, "start": "00:00:12.500", "end": "00:00:27.800", "shot_ids": [2, 3], "text": "切片文本" } ] } } ``` ## 进阶使用 ### 选择切片策略专业版通过 `strategy` 指定切片策略，请根据视频内容类型选择： * `short_drama`：短剧/剧情类内容，融合 OCR 与 ASR 并保护句子完整性。 * `movie_series`：影视剧内容，自动进行场景检测与语义合并。 * `mini_game`：小游戏录屏，过滤静止、低画质和弹窗片段。 * `custom`：自定义策略，可通过 `enable_scene_detection` 与 `avoid_sentence_cutoff` 参数控制场景检测和分句保护行为。 ### 控制切片时长范围您可以通过 `min_duration` 与 `max_duration` 控制单个切片的目标时长范围（单位：秒，取值范围均为 `[1, 600]`）： * `min_duration`：单个切片的最小时长，不传时默认为 3 秒，且不得大于 `max_duration`。 * `max_duration`：单个切片的最大时长，不传时默认为 30 秒，且不得小于 `min_duration`。 ### 使用自定义策略当内置策略不满足需要时，可将 `strategy` 设为 `custom`，并通过以下两个开关精细化控制切分行为（仅在 `strategy=custom` 时生效，其他策略使用各自的内置配置）： * `enable_scene_detection`：是否开启场景检测。默认为 `false`；开启后会在镜头切分基础上进行语义场景合并。 * `avoid_sentence_cutoff`：是否开启分句检测并尽量避免从一句话中间切断切片。默认为 `false`；该能力依赖 ASR/OCR，无可识别语音或字幕的视频建议关闭。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment-pro' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_long_video.mp4", "strategy": "custom", "min_duration": 5, "max_duration": 20, "enable_scene_detection": true, "avoid_sentence_cutoff": true }' ``` ### 返回镜头、场景与分句明细默认情况下（`include_detail_types` 不传时默认为 `["shot_list"]`）响应在切片列表 `segments` 之外还会返回镜头明细。如需调整返回的镜头、场景或分句明细，可通过 `include_detail_types` 指定（可多选）： * `shot_list`：返回镜头列表 `shots` 及镜头总数 `shot_count`。 * `scene_list`：返回场景分镜列表 `scenes` 及场景总数 `scene_count`；仅当 `strategy=movie_series`，或 `strategy=custom` 且 `enable_scene_detection=true` 时返回。 * `sentence_list`：返回分句结果列表 `sentences` 及分句总数 `sentence_count`；仅当所选策略启用分句检测且视频含可识别语音或字幕时返回，`mini_game` 策略固定不返回。 ### 返回实际切片视频默认情况下（`return_segment_videos=false`）响应只返回切片时间轴等 JSON 信息。若将 `return_segment_videos` 设为 `true`，系统会同时生成每个切片的视频文件，并在响应的 `segments[].video_url` 中返回下载链接。 ## 参考信息 ### 使用限制 |限制项 |说明 | |---|---| |输入文件限制 |* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

* **支持格式**：`mp4`, `flv`, `ts`, `avi`, `mov`, `wmv`, `mkv` 等主流视频格式。

* **视频时长**：单个视频时长不得超过 3.5 小时。 | ### 计费说明详细计费规则与单价请参见[智能语义切片（专业版，按输入时长计费）](https://docs.volcengine.com/docs/6448/2486473#e7fd9ab1)。 ## 相关 API 文档 * [提交智能语义切片（专业版）任务 API](https://docs.volcengine.com/docs/6448/2693717) * [查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532) * [事件回调](https://docs.volcengine.com/docs/6448/2288701)