POST https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment-pro

本 API 用于提交一个异步的智能语义切片（专业版）任务，结合镜头边界、场景语义、ASR/OCR 文本和时长约束，将长视频切成语义完整、时长合适的片段，支持短剧、影视剧、小游戏和自定义策略。详细的切片、镜头、场景及分句结果直接在任务结果中返回。

请求参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/media.mp4	待切片的视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。视频时长：单个视频时长不得超过 3.5 小时。
strategy	String	是	short_drama	切片策略，取值如下： short_drama：短剧/剧情类内容，融合 OCR 与 ASR 并保护句子完整性。 movie_series：影视剧内容，自动进行场景检测与语义合并。 mini_game：小游戏录屏，过滤静止、低画质和弹窗片段。 custom：自定义场景检测和句子完整性保护。
min_duration	Integer	否	3	单个切片的最小时长，单位秒，取值范围 [1, 600]，且不得大于 max_duration。不传时默认为 3 秒。
max_duration	Integer	否	30	单个切片的最大时长，单位秒，取值范围 [1, 600]，且不得小于 min_duration。不传时默认为 30 秒。
enable_scene_detection	Boolean	否	false	是否开启场景检测。仅当 strategy 为 custom 时生效；其他 strategy 选项会使用各自的内置配置，此参数无效。 true：开启场景检测。系统将在镜头切分基础上进行语义场景合并。 false：（默认）关闭场景检测。
avoid_sentence_cutoff	Boolean	否	false	是否开启分句检测并尽量避免从一句话中间切断切片。仅当 strategy 为 custom 时生效；其他 strategy 选项会使用各自的内置配置，此参数无效。 true：开启分句检测。系统将尝试在完整的句子边界进行切分。该能力依赖 ASR/OCR，对于无可识别语音或字幕的视频，开启后可能无明显效果。 false：（默认）关闭分句检测。
return_segment_videos	Boolean	否	false	是否生成并返回切片视频文件。 true：生成每个切片的视频文件，并在任务结果的 segments[].video_url 字段中返回其下载链接。 false：（默认）不生成切片视频，只返回切片的时间轴等元数据。
include_detail_types	Array	否	["shot_list", "scene_list"]	控制任务结果中包含哪些可选明细，可多选，支持取值： shot_list：镜头列表 scene_list：场景分镜列表 sentence_list：分句结果默认值为 ["shot_list"]，即不传时默认返回镜头列表。 *说明由于 Scene 对象和 Sentence 对象中的 shot_ids 字段引用了镜头列表 shots 中的具体信息，当您在 include_detail_types 中请求 scene_list 或 sentence_list 时，建议您同时包含 shot_list。否则，shot_ids 将无法在返回结果中直接找到对应的镜头详情。
media_output_destination	String	否	tos://<您的桶名>	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的对象存储（TOS）桶。您可将 media_output_destination 设为 tos://<您的桶名>。任务结果中的 url 相关字段将返回形如 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_135	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何对一个短剧视频进行专业版语义切片，并额外返回镜头明细。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值。您可以使用此 ID 来查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

智能语义切片是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一（轮询查询）：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二（事件回调）：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。其中切片列表 segments 始终返回；shots/scenes/sentences 等明细按请求参数 include_detail_types 与所选策略按需返回。

参数	类型	描述
duration	Number	输入视频总时长，单位秒，用于计量计费。
segment_count	Integer	切片总数。
segments	Array	语义切片列表，始终返回，按时间顺序排列。元素结构见下文 Segment 对象。
shot_count	Integer	镜头总数。仅当请求参数 include_detail_types 包含 shot_list 且底层工作流成功产出镜头结果时返回。
shots	Array	镜头列表。仅当请求参数 include_detail_types 包含 shot_list 且底层工作流成功产出镜头结果时返回。元素结构见下文 Shot 对象。
scene_count	Integer	场景分镜总数。仅当请求参数 include_detail_types 包含 scene_list，且 strategy 为 movie_series 或 strategy 为 custom 并设置 enable_scene_detection 为 true 时返回。
scenes	Array	场景分镜列表。仅当请求参数 include_detail_types 包含 scene_list，且 strategy 为 movie_series 或 strategy 为 custom 并设置 enable_scene_detection 为 true 时返回。元素结构见下文 Scene 对象。
sentence_count	Integer	分句结果总数。仅当请求参数 include_detail_types 包含 sentence_list、所选 strategy 启用分句检测，且视频中包含可识别的语音或字幕时返回。mini_game 策略固定不返回此列表。
sentences	Array	分句结果列表。仅当请求参数 include_detail_types 包含 sentence_list、所选 strategy 启用分句检测，且视频中包含可识别的语音或字幕时返回。mini_game 策略固定不返回此列表。元素结构见下文 Sentence 对象。

Segment 对象

参数	类型	描述
index	Integer	切片序号，从 0 开始按顺序递增。
start_ms	Integer	切片起始时间，单位毫秒。
end_ms	Integer	切片结束时间，单位毫秒。
start	String	切片起始时间，格式为 HH:MM:SS.mmm。
end	String	切片结束时间，格式为 HH:MM:SS.mmm。
shot_ids	Array	该切片包含的镜头 ID 列表。
text	String	该切片文本内容。mini_game 等无文本的策略不返回该字段。
video_url	String	切片视频下载链接，仅在 return_segment_videos=true 且成功生成视频时返回。

Shot 对象

仅当 include_detail_types 包含 shot_list 且底层产出镜头结果时返回。

参数	类型	描述
id	Integer	镜头 ID。
start_ms	Integer	镜头起始时间，单位毫秒。
end_ms	Integer	镜头结束时间，单位毫秒。
start	String	镜头起始时间，格式为 HH:MM:SS.mmm。
end	String	镜头结束时间，格式为 HH:MM:SS.mmm。
frames	Array	镜头起止帧号，格式为 [起始帧, 结束帧]。
text	String	镜头文本；无文本时不返回该字段。

Scene 对象

仅当请求参数 include_detail_types 包含 scene_list，且 strategy 为 movie_series 或 strategy 为 custom 并设置 enable_scene_detection 为 true 时返回。

参数	类型	描述
start_ms	Integer	场景起始时间，单位毫秒。
end_ms	Integer	场景结束时间，单位毫秒。
start	String	场景起始时间，格式为 HH:MM:SS.mmm。
end	String	场景结束时间，格式为 HH:MM:SS.mmm。
shot_ids	Array	该场景包含的镜头 ID 列表。

Sentence 对象

仅当请求参数 include_detail_types 包含 sentence_list、所选 strategy 启用分句检测，且视频中包含可识别的语音或字幕时返回。mini_game 策略固定不返回此列表。

参数	类型	描述
speaker_id	Integer	说话人 ID。
text	String	句子文本。
start_ms	Integer	句子起始时间，单位毫秒。
end_ms	Integer	句子结束时间，单位毫秒。
start	String	句子起始时间，格式为 HH:MM:SS.mmm。
end	String	句子结束时间，格式为 HH:MM:SS.mmm。
shot_ids	Array	该句子关联的镜头 ID 列表。

最终的完整任务信息示例：

AI MediaKit