文档中心

AI MediaKit

视频工具

智能语义切片（专业版）

AI MediaKit 的智能语义切片（专业版）工具，面向长视频理解、素材拆条和二次剪辑场景，在基础版的语义切分能力之上进一步结合镜头边界、场景语义、ASR/OCR 文本与时长约束，将长视频切成语义完整、时长合适的片段。相比智能语义切片（基础版），专业版内置短剧、影视剧、小游戏三套行业切片策略并支持自定义策略，且直接在响应中返回详细的切片、镜头、场景与分句结果。

本篇开发指南将引导您：

理解智能语义切片（专业版）的工作方式与内置切片策略。

快速从一个视频中获取语义切片结果。

学习如何按业务场景选择切片策略、控制切片时长范围，并按需返回镜头、场景与分句明细。

基础版与专业版对比

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 元/分钟

快速体验：获取视频语义切片结果

本节将通过一个具体的示例，演示如何为一个视频文件进行专业版语义切分，并获取所有语义片段的信息。

准备工作

获取访问凭证：在开始之前，访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 MediaKit API Key（用于媒体处理功能鉴权）。

准备视频文件：准备一个待处理的视频文件，并将其上传至公网可访问的服务器或视频点播服务中，以获取可供 API 调用的 URL。

操作流程

智能语义切片（专业版）是一个异步任务，整体流程如下：

成功调用 POST /api/v1/tools/semantic-segment-pro 提交任务后，您将获得一个唯一的 task_id。

您可以轮询查询任务信息 API，直到任务状态 status 变为 completed；或者使用事件回调自动接收任务状态变化。

任务完成后，直接解析响应中的 result 字段：segments 数组始终返回，包含所有语义片段的时间轴信息；shots/scenes/sentences 等明细字段按 include_detail_types 与所选策略按需返回。

第 1 步：提交任务

调用提交智能语义切片（专业版）任务 API。您可以直接复制以下 cURL 命令，向 API 提交一个基本的专业版语义切片任务。专业版必须通过 strategy 指定切片策略，本示例使用短剧策略 short_drama。

说明

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

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

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

请求成功后，您会收到如下包含 task_id 的响应，请保存此 ID 用于后续查询。

第 2 步：获取结果

由于视频处理需要时间，您需要通过轮询查询任务信息 API 来获取最终结果，直到任务状态变为 completed。

说明

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

当任务成功完成后，您将收到如下响应。切片结果直接在 result 字段中返回，segments 数组始终包含所有语义片段。

进阶使用

选择切片策略

专业版通过 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，无可识别语音或字幕的视频建议关闭。

返回镜头、场景与分句明细

默认情况下（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://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。

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

视频时长：单个视频时长不得超过 3.5 小时。

计费说明

详细计费规则与单价请参见智能语义切片（专业版，按输入时长计费）。