`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment-pro` 本 API 用于提交一个异步的智能语义切片（专业版）任务，结合镜头边界、场景语义、ASR/OCR 文本和时长约束，将长视频切成语义完整、时长合适的片段，支持短剧、影视剧、小游戏和自定义策略。详细的切片、镜头、场景及分句结果直接在任务结果中返回。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`video_url` |String |是 |`https://example.com/media.mp4` |待切片的视频 URL。

* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

* **支持格式**：`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 将无法在返回结果中直接找到对应的镜头详情。

说明

首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 \> 授权管理页面，授权 AI MediaKit 将文件写入您的 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。

| |`client_token` |String |否 |`your_unique_request_id_135` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_custom_callback_args` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://docs.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |`https://example.com/callback` |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://docs.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://docs.volcengine.com/docs/6448/2519520)。 | ## 请求示例以下示例演示了如何对一个短剧视频进行专业版语义切片，并额外返回镜头明细。 ```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", "min_duration": 5, "max_duration": 20, "include_detail_types": ["shot_list"] }' ``` ## 响应说明调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。 ### 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |`success` |Boolean |任务是否成功提交。

* `true`：任务已成功提交到后台处理队列。

* `false`：请求存在错误，任务提交失败。请检查 `error` 字段以获取详细信息。 | |`task_id` |String |任务的唯一标识符。仅在 `success` 为 `true` 时返回有效值。您可以使用此 ID 来查询任务状态和结果。 | |`request_id` |String |本次 API 请求的唯一标识符，可用于问题排查。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 Error 对象。 | #### Error 对象 |**参数** |**类型** |**描述** | |---|---|---| |`code` |String |具体的错误码。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)。 | |`type` |String |错误的宏观类型。例如 `BadRequest`。 | |`message` |String |对错误的详细描述，可用于开发调试。 | |`param` |String |（可选）指出导致错误的具体参数。 | ### 响应示例 #### 成功响应 ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-pro-123456789", "request_id": "20260807130000ABCDEFG12345" } ``` #### 失败响应 ```JSON { "success": false, "task_id": "", "request_id": "20260807130500XYZW12345", "error": { "code": "InvalidParameter", "message": "`strategy` is required.", "param": "strategy", "type": "BadRequest" } } ``` ## 异步任务结果智能语义切片是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果： * **方法一（轮询查询）：** 使用提交任务时获取的 `task_id`，定期调用[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532)，直到 `status` 字段变为 `completed` 或 `failed`。 * **方法二（事件回调）：** 在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 `callback_url` 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅[事件回调](https://docs.volcengine.com/docs/6448/2288701)。当任务成功完成后，您获取到的任务信息中的 `result` 字段将包含以下内容。其中切片列表 `segments` 始终返回；`shots`/`scenes`/`sentences` 等明细按请求参数 `include_detail_types` 与所选策略按需返回。 |参数 |类型 |描述 | |---|---|---| |`duration` |Number |输入视频总时长，单位秒，用于计量计费。 | |`segment_count` |Integer |切片总数。 | |`segments` |Array |语义切片列表，始终返回，按时间顺序排列。元素结构见下文 [Segment 对象](https://docs.volcengine.com/docs/6448/2693717#1cc6053c)。 | |`shot_count` |Integer |镜头总数。仅当请求参数 `include_detail_types` 包含 `shot_list` 且底层工作流成功产出镜头结果时返回。 | |`shots` |Array |镜头列表。仅当请求参数 `include_detail_types` 包含 `shot_list` 且底层工作流成功产出镜头结果时返回。元素结构见下文 [Shot 对象](https://docs.volcengine.com/docs/6448/2693717#shot-%E5%AF%B9%E8%B1%A1)。 | |`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 对象](https://docs.volcengine.com/docs/6448/2693717#scene-%E5%AF%B9%E8%B1%A1)。 | |`sentence_count` |Integer |分句结果总数。仅当请求参数 `include_detail_types` 包含 `sentence_list`、所选 `strategy` 启用分句检测，且视频中包含可识别的语音或字幕时返回。`mini_game` 策略固定不返回此列表。 | |`sentences` |Array |分句结果列表。仅当请求参数 `include_detail_types` 包含 `sentence_list`、所选 `strategy` 启用分句检测，且视频中包含可识别的语音或字幕时返回。`mini_game` 策略固定不返回此列表。元素结构见下文 [Sentence 对象](https://docs.volcengine.com/docs/6448/2693717#sentence-%E5%AF%B9%E8%B1%A1)。 | ### 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 列表。 | 最终的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-pro-123456789", "request_id": "20260807130000ABCDEFG12345", "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": "切片文本", "video_url": "https://example.volcvideo.com/segment_0.mp4?auth_key=..." }, { "index": 1, "start_ms": 12500, "end_ms": 27800, "start": "00:00:12.500", "end": "00:00:27.800", "shot_ids": [2, 3], "text": "切片文本", "video_url": "https://example.volcvideo.com/segment_1.mp4?auth_key=..." } ], "shot_count": 4, "shots": [ { "id": 0, "start_ms": 0, "end_ms": 4500, "start": "00:00:00.000", "end": "00:00:04.500", "frames": [1, 135], "text": "对话文本" } ] }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ```