POST https://mediakit.cn-beijing.volces.com/api/v1/tools/asr-subtitles

本接口用于提交一个异步的语音转字幕（ASR）任务，对输入的视频或音频进行语音识别，输出带时间戳的字幕文本。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
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 小时。注意 video_url 和 audio_url 必须提供其中一个。都存在时优先取 video_url。
audio_url	String	条件必选	https://example.com/media.mp3	待处理的音频 URL。文件来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp3, m4a, wav 等主流音频格式。文件时长：文件时长不超过 3 小时。注意 video_url 和 audio_url 必须提供其中一个。都存在时优先取 video_url。
content_type	String	否	speech	识别内容类型。如果留空，算法将自动探测。 speech：普通说话 singing：唱歌
language	String	否	cmn-Hans-CN	识别语种。如果留空，算法将自动探测语种。支持的取值如下： cmn-Hans-CN：简体中文 eng-US：英语 spa-ES：西班牙语 ind-ID：印尼语
enable_speaker_info	Boolean	否	true	是否开启说话人识别。默认为 false。开启后，结果中会包含 speaker 字段。
enable_confidence	Boolean	否	true	是否返回每个字幕片段的置信度。默认为 false。开启后，结果中会包含 confidence 字段。
client_token	String	否	your_unique_request_id_133	用户请求凭证，用于幂等控制。大小写敏感，不超过 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 Key 分账。

请求示例

以下示例演示了如何对一个中文视频进行语音转字幕，并开启说话人识别。

响应说明

任务提交后，接口会立即返回以下 JSON 对象。其中包含任务的唯一标识 task_id。请保存此 ID 用于后续查询。

参数	类型	描述
success	Boolean	任务是否提交成功。 true：成功。 false：失败。更多信息请查看错误处理。
task_id	String	任务的唯一标识，用于后续查询任务进度和结果。
request_id	String	本次请求的唯一标识，可用于问题排查。

响应示例：

异步任务结果

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

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

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

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。

参数	类型	描述
subtitles	Array	字幕片段列表。每个元素是一个包含字幕文本和时间戳的对象，详见下文Subtitle 对象。
duration	Number	输入音频或视频的总时长（单位：秒）。

Subtitle 对象

参数	类型	描述
subtitle_text	String	识别出的字幕文本。
start_time	Number	该字幕片段的起始时间（单位：秒）。
end_time	Number	该字幕片段的结束时间（单位：秒）。
speaker	String	说话人标识。仅当请求中 enable_speaker_info 为 true 时返回。
confidence	Number	该字幕片段的置信度得分（0 到 1 之间）。仅当请求中 enable_confidence 为 true 时返回。

以下是一个任务执行完成后的完整任务信息示例：

错误处理

当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见错误码。示例如下：

AI MediaKit