AI MediaKit 的智能语义切片（基础版）工具，基于视频内容语义理解，将一个长视频精准地切分为多个具备完整语义单元的片段，并输出每个片段的起止时间轴信息。与传统的基于转场/画面差异的镜头切分不同，智能语义切片会综合分析画面、语音与叙事结构，确保切点在语义上是完整的（例如，不会从一句话中间切断），让切片更贴合“可独立表达一段完整语义”的边界，适合用于短视频拆条、剪辑素材召回、多模态数据标注等场景。本篇开发指南将引导您： * 理解智能语义切片的工作方式。 * 快速从一个视频中获取语义切片的时间码结果。 * 学习如何调整目标切片时长范围与容忍度以贴合业务需要。 ## 快速体验：获取视频语义切片时间轴本节将通过一个具体的示例，演示如何为一个视频文件进行智能语义切分，并获取所有语义片段的起止时间戳。 ### 准备工作 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` 提交任务后，您将获得一个唯一的 `task_id`。 2. 您可以轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532)，直到任务状态 `status` 变为 `completed`；或者使用[事件回调](https://www.volcengine.com/docs/6448/2288701)自动接收任务状态变化。 3. 任务完成后，解析响应中的 `result` 字段：`result_url` 指向一份 gzip 压缩的 JSON 文件，其中的 `segments` 数组包含所有语义片段的时间轴信息。 #### 第 1 步：提交任务调用[提交智能语义切片任务 API](https://www.volcengine.com/docs/6448/2563057)。您可以直接复制以下 cURL 命令，向 API 提交一个基本的语义切片任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_long_video.mp4" }' ```

说明

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

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

请求成功后，您会收到如下包含 `task_id` 的响应，请保存此 ID 用于后续查询。 ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-123456789", "request_id": "20260702130000ABCDEFG12345" } ``` #### 第 2 步：获取结果由于视频处理需要时间，您需要通过轮询[查询任务信息 API](https://www.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` 字段中的 `result_url` 指向 gzip 压缩后的 JSON 结果文件。 ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-123456789", "status": "completed", "result": { "duration": 185.5, "segment_count": 12, "result_url": "https://example.volcvideo.com/semantic_segments.json.gz?auth_key=..." } } ``` 下载并解压 `result_url` 指向的文件，即可获得完整的切片结果，示例结构如下： ```JSON { "duration_ms": 185500, "duration": 185.5, "has_audio": true, "segment_count": 12, "segments": [ {"index": 0, "start_ms": 0, "end_ms": 12350, "start": "00:00:00.000", "end": "00:00:12.350"}, {"index": 1, "start_ms": 12350, "end_ms": 27800, "start": "00:00:12.350", "end": "00:00:27.800"}, ... ] } ``` ## 进阶使用 ### 调整切分粒度您可以通过 `min_duration`、`max_duration` 与 `max_shift_tolerance` 三个参数，精细化地控制语义切片的目标时长范围与边界容忍度： * `min_duration`：切片的目标最小时长（单位：秒），默认值为 3，最小值为 1。小于此值的片段会与相邻切片合并（前提是合并后不超过 `max_duration`），以避免产生过短的碎片（例如，快速闪回镜头）。 * `max_duration`：切片的目标最大时长（单位：秒）。默认值为 30，最小值为 1。超过此值将触发强制切分，保证片段不会过长。 * `max_shift_tolerance`：切点偏移容忍度（单位：秒）。默认值为 0，最小值为 0。设为大于 0 时，算法会在切点前后该范围内寻找更贴近语义的位置（如句末、停顿），让切点尽量落在自然停顿处而不是句子中间。该值越大，切点越贴合语义，但切片实际时长相对 `min_duration` 或 `max_duration` 的抖动也越大。以下示例中，API 将会： * 目标语义切片时长控制在 5~20 秒； * 在语义边界附近允许最多 ±2 秒的浮动，尽量对齐到更清晰的镜头或语音停顿点。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_long_video.mp4", "min_duration": 5, "max_duration": 20, "max_shift_tolerance": 2 }' ``` ## 参考信息 ### 使用限制 |限制项 |说明 | |---|---| |输入文件限制 |* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://www.volcengine.com/docs/6448/2536893)。

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

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