`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/segment-scenes` 本接口用于提交一个异步的场景切分任务，依据视频的转场和画面内容变化，自动将视频切分为多个场景片段，并输出每个片段的时间轴信息与对应的独立视频文件。 * **获取任务结果**：任务提交成功后，您需要保存返回的 `task_id`，并通过轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或配置[事件回调](https://www.volcengine.com/docs/6448/2288701)获取最终结果。 * **开发指南**：如需了解完整的使用流程和应用示例，请参阅[场景切分](https://www.volcengine.com/docs/6448/2381963)。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_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` 等主流视频格式。

* **视频时长**：单个视频时长不超过 2 小时。 | |`return_segment_videos` |Boolean |否 |`true` |是否生成并返回切片视频文件。

* `true`：（默认）生成切片文件，并在 `result.segments[].segment_video_url` 返回各切片的下载链接。

* `false`：不生成切片文件，仅返回切片时间轴（`start_time` / `end_time`），不返回 `segment_video_url` 。适用于只需获取场景时间码、由业务侧自行处理切片的场景，可降低任务耗时。 | |`segment_threshold` |Number |否 |`10` |场景切分的敏感度阈值。取值范围为 [0, 100)。

* 取值越低，算法对场景变化的感知越敏感，切分出的片段越多。

* 取值越高，算法越倾向于将微小的变化视为同一场景，切分出的片段越少。

当您同时设置 `min_duration`, `max_duration` 和 `segment_threshold` 时，系统会按照以下两阶段逻辑进行切分，以确保所有约束都得到满足：

1. 算法首先会根据您设置的 `segment_threshold` 和 `min_duration` 进行切分。

2. 第一阶段切分完毕后，如发现有切片的时长超过您设置的 `max_duration`，系统会忽略 `segment_threshold` 的影响，再进行切分，确保最终时长都不超过 `max_duration`。 | |`min_duration` |Number |否 |`3` |单个切片的最小时长（单位：秒）。小于此时间的片段将被合并。默认值为 3。应小于或等于 `max_duration`。 | |`max_duration` |Number |否 |`30` |单个切片的最大时长（单位：秒）。大于此时间的片段将被强制切分。默认值为 30。应大于或等于 `min_duration`。 | |`enable_clip_fade` |Boolean |否 |`false` |是否将检测到的淡入/淡出片段作为独立的切片输出。默认为 `false`。

* `false`:（默认）不独立输出。淡入/淡出片段会被视为其前后场景的一部分，合并到相邻的切片中。

* `true`: 独立输出。如果视频中存在明显的淡入/淡出过渡，系统会将其分割成一个独立的切片。 | |`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/segment-scenes' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_long_video.mp4", "segment_threshold": 10, "min_duration": 3, "enable_clip_fade": true }' ``` ## 响应说明 ### 任务提交成功响应任务提交成功后，接口会立即返回以下 JSON 对象。 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否提交成功。

* `true`：成功。

* `false`：失败。更多信息请查看[错误处理](https://www.volcengine.com/docs/6448/2386118#UDzxhpadZz)。 | |`task_id` |String |任务的唯一标识，用于后续查询任务进度和结果。 | |`request_id` |String |本次请求的唯一标识，可用于问题排查。 | 示例： ```JSON { "success": true, "task_id": "amk-tool-segment-scenes-123456789", "request_id": "20240521130000ABCDEFG12345" } ``` ### 异步任务结果任务处理完成后，通过[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或[事件回调](https://www.volcengine.com/docs/6448/2288701)获取的 `result` 字段将包含以下内容。 |参数 |类型 |描述 | |---|---|---| |`segments` |Array |切片信息列表。每个元素是一个包含切片起止时间等信息的对象。详细结构见下方的 [Segment 对象](https://www.volcengine.com/docs/6448/2386118#30cc2b64)。 | |`duration` |Number |输入视频的总时长（单位：秒）。 | #### Segment 对象 |参数 |类型 |描述 | |---|---|---| |`start_time` |Number |切片的起始时间（单位：秒）。 | |`end_time` |Number |切片的结束时间（单位：秒）。 | |`segment_video_url` |String |切片视频文件的下载地址，有效期为 24 小时，输出视频为 MP4 格式。仅当请求参数 `return_segment_videos` 为 `true`（默认）时返回；当 `return_segment_videos` 为 `false` 时不生成切片文件，本字段不返回。 | 最终的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-segment-scenes-123456789", "request_id": "20240521130000ABCDEFG12345", "result": { "duration": 185.5, "segments": [ { "start_time": 0.0, "end_time": 15.2, "segment_video_url": "https://example.volcvideo.com/segment1.mp4?auth_key=..." }, { "start_time": 15.2, "end_time": 45.8, "segment_video_url": "https://example.volcvideo.com/segment2.mp4?auth_key=..." }, { "start_time": 45.8, "end_time": 185.5, "segment_video_url": "https://example.volcvideo.com/segment3.mp4?auth_key=..." } ] }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851, "request_id": "202604272009269BA43D771246AFF513F0" } ``` ## 错误处理当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见[错误码](https://www.volcengine.com/docs/6448/2300662)。示例如下： ```JSON { "success": false, "task_id": "", "request_id": "20240521130500XYZW12345", "error": { "code": "InvalidParameter", "message": "`min_duration` cannot be greater than `max_duration`.", "param": "min_duration, max_duration", "type": "BadRequest" } } ```