POST https://mediakit.cn-beijing.volces.com/api/v1/tools/probe-audio-metadata

本 API 用于提交一个异步的音频元信息获取任务，对输入的音频 URL进行探测，输出标准化的媒资元信息，包含容器层信息（format_meta）与音频流信息（audio_stream_meta）。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
audio_url	String	是	https://example.com/audio.mp3	待探测的音频 URL。文件来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp3, m4a, wav, wma, amr, aac, ogg, flac 等音频格式。
client_token	String	否	your_unique_request_id_132	用户请求凭证，用于幂等控制。大小写敏感，不超过 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 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值。您可以使用此 ID 来查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

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

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

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

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

参数	类型	描述
format_meta	Object	容器层元信息，包含封装格式、码率、时长、大小等。详见 Format meta 对象。
audio_stream_meta	Object	主音频流元信息。如果音频不含音频流，则返回 null。详见 Audio stream meta 对象。

Format meta 对象

参数	类型	描述
md5	String	文件 MD5 值（如可获取）。
container	String	容器格式（封装格式），例如 mp3。
bitrate	Number	容器码率，单位为 bps。
duration	Number	容器声明的时长，单位为秒。
size	Number	文件大小，单位为 Byte。

Audio stream meta 对象

参数	类型	描述
codec	String	音频编码格式，例如 aac。
duration	Number	音频流的时长，单位为秒。
sample_rate	Number	音频采样率，单位为 Hz。
bitrate	Number	音频流码率，单位为 bps。
channels	Number	音频声道数。

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

AI MediaKit