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

本 API 用于提交一个异步的音频转码任务。音频转码是将一个音频码流转换成另一个音频码流的过程，通常涉及编码格式（如 AAC）、编码参数（如采样率、码率）、封装格式（如 MP3）等的转换，以适应不同的业务场景、播放终端和网络环境。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
audio_url	String	是	https://example.com/source.wav	待转码的音频 URL。文件来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp3, m4a, wav, wma, amr, aac, ogg, flac 等音频格式。
container_format	String	否	MP3	目标封装格式。建议填写。系统会根据封装格式自动选择对应的编码器： MP3：（默认）编码器为 MP3 M4A：编码器为 AAC OGG：编码器为 Opus
audio	Object	否	-	音频参数配置。详见下文 Audio 对象（音频转码参数）。
metadata_keep_tags	Array of Strings	否	["title", "artist"]	需要从源音频保留的元信息标签列表。默认情况下，转码过程会丢弃大部分元信息（如标题、艺术家等）。使用此参数可以指定需要保留的标签键（Key）。
metadata_add_tags	Array of Objects	否	[{"key": "album", "value": "Remastered 2024"}]	需要为输出音频新增的元信息标签列表，每个标签由 key 和 value 组成。如果新增的标签与被保留的标签同名，此处的设置会覆盖源文件的值。
media_output_destination	String	否	vod://my-space	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
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。详情请参考项目与队列管理。

Audio 对象（音频转码参数）

参数	类型	是否必选	示例值	描述
sample_rate	Integer	否	44100	音频采样率，单位为 Hz。默认为 48000。建议根据您的目标编码器填写。不同编码器支持的采样率不同： MP3 支持：8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000 AAC 支持：8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000 Opus 支持：48000
bitrate_mode	String	否	cbr	音频码率控制模式。支持取值如下： cbr ：（默认）恒定码率模式。编码器会尝试使音频流的每一秒都严格保持在 bitrate_kbps 参数设定的码率。这使得文件大小可以被精确预测，适合对带宽稳定性要求高的流式传输场景。 cae：自适应码率模式（仅 container_format 为 M4A 时支持）。编码器会根据音频内容的复杂度动态调整瞬时码率，但会确保整个文件的平均码率接近 bitrate_kbps 参数设定的目标值。
bitrate_kbps	Integer	否	192	音频码率，单位为 Kbps。取值范围 [10, 500]，默认值为 128。为空时，输出音频的码率和原始音频保持一致。
channels	Integer	否	2	音频声道数。支持以下取值： 1：单声道 2：（默认）双声道
volume_method	String	否	2Pass	音量均衡算法开关。将此参数设置为 2Pass 可启用两阶段响度分析与处理，此时 volume_integrated_loudness、 volume_true_peak、volume_loudness_range 参数将生效。不设置此参数则不处理音量。
volume_integrated_loudness	Number	否	-14	目标综合响度，用于设定音频的整体感知音量，单位 LUFS。取值范围 [-70, -5]，默认值为 -12。当 volume_method 为 2Pass 时生效且必填。
volume_true_peak	Number	否	-1.5	真实峰值电平，用于设置音频信号的最高上限以防止削波失真，单位 dBTP。取值范围 [-9, 0]，默认值为 0。当 volume_method 为 2Pass 时生效且必填。
volume_loudness_range	Number	否	7	响度范围（动态范围），用于调节音频中最响亮和最安静部分之间的差异，单位 LU。取值范围 [1, 20]，默认值为 7。当 volume_method 为 2Pass 时生效。

请求示例

以下示例演示了如何提交一个音频转码任务，将源音频转换为 MP3 格式，码率设为 192 Kbps，并开启音量均衡。

响应说明

调用 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 字段将包含以下内容。

参数	类型	描述
audio_url	String	输出音频的地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	音频时长，单位为秒。

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

AI MediaKit