`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/detect-voice-activity` 本 API 用于提交一个异步的语音端点识别任务，自动定位音频或视频文件中有效语音的起止时间，将人声和静音、背景噪声等无效片段区分开来，返回一个包含所有有效人声片段起止时间戳的列表，为后续识别、分析、剪辑和训练提供更干净的音频输入。 * **获取任务结果**：任务提交成功后，您需要保存返回的 `task_id`，并通过轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或配置[事件回调](https://www.volcengine.com/docs/6448/2288701)获取最终结果。 * **开发指南**：如需了解完整的使用流程和应用示例，请参阅[语音端点识别](https://www.volcengine.com/docs/6448/2578379)。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考 [获取 API Key](https://www.volcengine.com/docs/6448/2300661#82bd96fd)。 | ### 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` 等主流视频格式。

注意：`video_url` 和 `audio_url` 必须且只能提供其中一个。 | |`audio_url` |String |条件必选 |`https://example.com/media.mp3` |待处理的音频 URL。

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

* **支持格式**：`mp3`, `m4a`, `wav`, `wma`, `amr`, `aac`, `ogg`, `flac` 等主流音频格式。

注意：`video_url` 和 `audio_url` 必须且只能提供其中一个。 | |`client_token` |String |否 |`your_unique_request_id_132` |用户请求凭证，用于幂等控制。大小写敏感，不超过 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/detect-voice-activity' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "audio_url": "https://example.com/your_audio.mp3" }' ``` ## 响应说明 ### 任务提交成功响应任务提交成功后，接口会立即返回以下 JSON 对象。 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否提交成功。

* `true`：成功。

* `false`：失败。更多信息请查看[错误处理](https://www.volcengine.com/docs/6448/2582742#MfXrcjE3x2)。 | |`task_id` |String |任务的唯一标识，用于后续查询任务进度和结果。 | |`request_id` |String |本次请求的唯一标识，可用于问题排查。 | 示例： ```JSON { "success": true, "task_id": "amk-tool-detect-voice-activity-123456789", "request_id": "20240521100000ABCDEFG12345" } ``` ### 异步任务结果任务处理完成后，通过[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或[事件回调](https://www.volcengine.com/docs/6448/2288701)获取的 `result` 字段将包含以下内容。 |参数 |类型 |描述 | |---|---|---| |`voice_segments` |Array of Object |有效人声片段列表。如果未检测到有效人声，则返回空数组 `[]`。数组中每个对象的结构见下文 [voice_segment 结构](https://www.volcengine.com/docs/6448/2582742#daf3e638)。 | |`segment_count` |Integer |检测到的人声片段数量。如果未检测到，则为 `0`。 | |`duration` |Number |输入媒体文件的总时长，单位为秒。 | #### voice_segment 结构 `voice_segments` 数组中的每个对象都包含以下字段： |参数 |类型 |示例值 |描述 | |---|---|---|---| |`start_time` |Number |`0.52` |片段开始时间，单位为秒，精确到小数点后两位。 | |`end_time` |Number |`4.34` |片段结束时间，单位为秒，精确到小数点后两位。 | 最终的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-detect-voice-activity-123456789", "request_id": "20240521100000ABCDEFG12345", "result": { "voice_segments": [ { "start_time": 0.52, "end_time": 4.34 }, { "start_time": 5.50, "end_time": 7.12 } ], "segment_count": 2, "duration": 15.5 }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ``` ## 错误处理当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见[错误码](https://www.volcengine.com/docs/6448/2300662)。示例如下： ```JSON { "success": false, "task_id": "", "request_id": "20240521100500XYZW12345", "error": { "code": "InvalidParameter", "message": "`video_url` and `audio_url` are mutually exclusive; exactly one must be provided.", "param": "video_url, audio_url", "type": "BadRequest" } } ```

智能处理