`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment` 本 API 用于提交一个异步的智能语义切片任务，综合分析视频的画面、语音和叙事结构，在保证语义完整（如避免将单句从中间切断）的前提下，通过镜头切换、语音停顿检测等策略，将长视频智能地切分为多个独立的素材片段。 * **获取任务结果**：任务提交成功后，您需要保存返回的 `task_id`，并通过轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或配置[事件回调](https://www.volcengine.com/docs/6448/2288701)获取最终结果。 * **开发指南**：如需了解完整的使用流程和应用示例，请参阅[智能语义切片](https://www.volcengine.com/docs/6448/2558632)。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_MediaKit_API_Key}` |格式为 `Bearer {Your_MediaKit_API_Key}`。请参考[基础概念及准备工作](https://www.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`video_url` |String |是 |`https://example.com/media.mp4` |待处理的视频 URL。

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

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

* **视频时长**：单个视频时长不得超过 3 小时。 | |`min_duration` |Number |否 |`3` |单个切片的**目标最小时长**（单位：秒）。小于此值的片段会与相邻切片合并（前提是合并后不超过 `max_duration`），以避免产生过短的碎片（例如，快速闪回镜头）。默认值为 `3`，最小值为 `1`，且必须小于或等于 `max_duration`。 | |`max_duration` |Number |否 |`30` |单个切片的**目标最大时长**（单位：秒）。超过此值将触发强制切分，保证片段不会过长。默认值为 `30`，最小值为 `1`，且必须大于或等于 `min_duration`。 | |`max_shift_tolerance` |Number |否 |`2` |切点偏移容忍度（单位：秒）。默认值为 0，最小值为 0，且必须小于或等于 `min_duration`。设为大于 0 时，算法会在切点前后该范围内寻找更贴近语义的位置（如句末、停顿），让切点尽量落在自然停顿处而不是句子中间。该值越大，切点越贴合语义，但切片实际时长相对 `min_duration` 或 `max_duration` 的抖动也越大。 | |`client_token` |String |否 |`your_unique_request_id_135` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://www.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_custom_callback_args` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://www.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |`https://example.com/callback` |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://www.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://www.volcengine.com/docs/6448/2519520)。 | ## 请求示例以下示例演示了如何对一个视频进行智能语义切片，并指定目标切片时长范围与边界浮动容忍度。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/semantic-segment' \ -H 'Authorization: Bearer {Your_MediaKit_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 }' ``` ## 响应说明 ### 任务提交成功响应任务提交成功后，接口会立即返回以下 JSON 对象。 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否提交成功。

* `true`：成功。

* `false`：失败。更多信息请查看[错误处理](https://www.volcengine.com/docs/6448/2563057#%E9%94%99%E8%AF%AF%E5%A4%84%E7%90%86)。 | |`task_id` |String |任务的唯一标识，用于后续查询任务进度和结果。 | |`request_id` |String |本次请求的唯一标识，可用于问题排查。 | 示例： ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-123456789", "request_id": "20260702130000ABCDEFG12345" } ``` ### 异步任务结果当任务处理完成后，通过[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或[事件回调](https://www.volcengine.com/docs/6448/2288701)获取的 `result` 字段将包含以下内容。 |参数 |类型 |描述 | |---|---|---| |`result_url` |String |语义切片结果文件的下载 URL。文件为 **gzip 压缩后的 JSON**，包含 `source` / `duration_ms` / `duration` / `has_audio` / `segment_count` / `segments` 等字段。URL 有效期为 24 小时。 | |`duration` |Number |输入视频的总时长（单位：秒）。 | |`segment_count` |Integer |最终切分出的语义片段数量。 | 最终的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-semantic-segment-123456789", "request_id": "20260702130000ABCDEFG12345", "result": { "duration": 185.5, "segment_count": 12, "result_url": "https://example.volcvideo.com/semantic_segments.json.gz?auth_key=..." }, "expires_at": 1783641650, "created_at": 1783468767, "finished_at": 1783468851 } ``` `result_url` 指向的 JSON 结果文件结构如下： ```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" } ] } ``` #### Segment 对象 |参数 |类型 |描述 | |---|---|---| |`index` |Integer |切片在结果中的顺序索引，从 `0` 开始。 | |`start_ms` |Integer |切片起始时间（单位：毫秒）。 | |`end_ms` |Integer |切片结束时间（单位：毫秒）。 | |`start` |String |切片起始时间，格式为 `HH:mm:ss.SSS`。 | |`end` |String |切片结束时间，格式为 `HH:mm:ss.SSS`。 | ## 错误处理当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见[错误码](https://www.volcengine.com/docs/6448/2300662)。示例如下： ```JSON { "success": false, "task_id": "", "request_id": "20260702130500XYZW12345", "error": { "code": "InvalidParameter", "message": "`min_duration` must be less than or equal to `max_duration`.", "param": "min_duration", "type": "BadRequest" } } ```

智能处理