POST https://mediakit.cn-beijing.volces.com/api/v1/tools/martencode-video

本 API 用于提交一个异步的极智超清转码任务。极智超清基于人眼视觉系统特性，在转码过程中对视频的场景、动作、内容、纹理等进行智能分析，并选择最优的编码参数，以相对较低的码率输出主观画质更优的视频。这能在降低带宽成本的同时，为您的用户带来更好的视觉体验。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example-video.com/input.mov	待转码的视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, mov, mkv, flv, ts, avi, wmv 等主流视频格式
container_format	String	是	MP4	输出视频的封装格式。支持取值如下： MP4 (默认) FLV MPEGTS
video	Object	是	-	视频转码参数配置。详见下文 Video 对象（视频转码参数）。
audio	Object	否	-	音频转码参数配置。如不传入此对象，则音频将采用默认参数进行转码（编码格式为 aac，其余参数跟随源文件）。详见下文Audio 对象（音频转码参数）。
metadata_keep_tags	Array of Strings	否	["title", "artist"]	需要从源视频保留的元信息标签列表。默认情况下，转码过程会丢弃大部分元信息（如标题、艺术家等）。使用此参数可以指定需要保留的标签键（Key）。此参数对 MPEGTS 封装格式无效。
metadata_add_tags	Array of Objects	否	[{"key": "album", "value": "2024 Remaster"}]	需要为输出视频新增的元信息标签列表，每个标签由 key 和 value 组成。如果新增的标签与被保留的标签同名，此处的设置会覆盖源文件的值。此参数对 MPEGTS 封装格式无效。
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。详情请参考项目与队列管理。

Video 对象（视频转码参数）

参数	类型	是否必选	示例值	描述
codec	String	是	h264	视频编码格式。默认为 h264。支持取值：h264, h265。
scale_type	Integer	否	2	视频画面缩放模式。默认为 0。 0：跟随片源模式。此模式下，不进行任何缩放，scale_mode、scale_width、scale_height、scale_short 和 scale_long 参数均无效。此模式下支持最高 8K 分辨率。 1：长短边限制模式。此模式激活 scale_short 和 scale_long 参数。您可以设置视频输出画面的长边或短边，另一边将按原视频比例自动缩放。此模式下支持最高 4K 分辨率。 2：宽高限制模式。此模式激活 scale_width 和 scale_height 参数。您可以设置视频输出画面的宽度或高度，另一边将按原视频比例自动缩放。此模式下支持最高 4K 分辨率。
scale_mode	Integer	否	2	视频画面填充与拉伸策略。此参数仅在 scale_type 为 1 或 2 时生效，用于处理您设定的目标尺寸与原视频的宽高比不一致的问题。默认为 0。 0：不上采，原片比目标大时缩小，原片比目标小时保持原尺寸。 1：拉伸上采，强制拉伸到目标宽高，可能导致画面变形。 2：补黑边上采，等比缩放到目标框内，不足部分用黑边填充。例如，您将一个 16:9 的视频，强制指定输出为 1:1 的 scale_width 和 scale_height： scale_mode 为 1 ，系统会将画面压扁或拉长以填满整个 1:1 的画布。 scale_mode 为 2，系统会保持原视频比例，将其完整放入 1:1 的画布中，并在上下或左右两侧填充黑边。
scale_width	Integer	否	1920	目标宽度，单位为 px。取值范围 [0, 4320]。仅当 scale_type 为 2（宽高限制模式）时生效。如果只传 scale_width 或 scale_height 之一，则另一边按比例缩放。
scale_height	Integer	否	1080	目标高度，单位为 px。取值范围 [0, 4320]。仅当 scale_type 为 2（宽高限制模式）时生效。如果只传 scale_width 或 scale_height 之一，则另一边按比例缩放。
scale_short	Integer	否	720	目标短边，单位为 px。取值范围 [0, 4320]。仅当 scale_type 为 1（长短边限制模式）时生效。如果只传 scale_short 或 scale_long 之一，则另一边按比例缩放。
scale_long	Integer	否	1280	目标长边，单位为 px。取值范围 [0, 4320]。仅当 scale_type 为 1（长短边限制模式）时生效。如果只传 scale_short 或 scale_long 之一，则另一边按比例缩放。
bitrate_mode	String	是	crf	码率控制模式。默认为 crf。 crf：恒定画质 (Constant Rate Factor) 模式。系统会尽量保证视频的整体视觉质量在 bitrate_crf 设定的水平上（值越小，质量越高），同时确保瞬时码率不超过 bitrate_kbps 的限制。这是在保证画质和控制文件大小之间取得平衡的最佳选择，推荐在大多数场景下使用。 abr：平均码率 (Average Bitrate) 模式。编码器会调整码率，使得最终输出视频的整体平均码率接近 bitrate_kbps 设定的值。适用于需要将文件大小控制在特定范围的场景。 cbr：恒定码率 (Constant Bitrate) 模式。编码器会尝试让视频流的每一秒都严格保持在 bitrate_kbps 设定的码率。画质会随画面复杂度波动，但码率非常稳定。适用于对网络传输稳定性有极高要求的流媒体场景。
bitrate_crf	Number	否	23	CRF（Constant Rate Factor）参数，仅当 bitrate_mode 为 crf 时生效，即 crf 模式下的主要质量控制器。取值范围 [0, 51]，默认为 25。数字越小，画质越高，文件体积越大。0 表示无损。
bitrate_kbps	Integer	是	2500	视频码率的目标值，单位 Kbps。取值范围 [10, 50000]，默认为 2000。其具体作用由 bitrate_mode 决定： crf 模式下：作为最大码率限制。 abr 模式下：作为平均码率目标。 cbr 模式下：作为恒定码率目标。
fps_mode	String	否	vfr	帧率控制模式。只有在您设置了 fps 参数后，fps_mode 才会生效。如果您不提供 fps 参数，系统将完全遵循原视频的帧率，fps_mode 的设置会被忽略。默认为 vfr。 vfr：动态帧率模式。fps 的值为最高帧率限制。如果原视频帧率低于您设定的 fps 值，则保留原帧率；如果高于 fps 值，则会降低到 fps 值。这有助于在不必要时避免帧率的过度提升。 cfr：恒定帧率模式。fps 的值为强制的输出帧率。无论原视频帧率是多少，输出视频都将被强制转换为 fps 设定的恒定帧率。
fps	Integer	否	30	目标帧率，取值范围 [1, 240]。设置此参数会激活 fps_mode 的逻辑。在 vfr 模式下代表最大帧率，在 cfr 模式下代表恒定帧率。如不设置，则完全遵循原视频帧率。
is_hdr_to_sdr	Boolean	否	true	是否将 HDR（高动态范围）视频转换为 SDR（标准动态范围）视频。默认为 true。设置为 false 则保留 HDR。

Audio 对象（音频转码参数）

参数	类型	是否必选	示例值	描述
codec	String	是	aac	音频编码格式。默认为 aac。当前仅支持 aac。
sample_rate	Integer	是	44100	音频采样率，单位为 Hz。默认为 44100。当前 aac 编码支持的采样率包括：8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000。
bitrate_mode	String	是	cbr	音频码率控制模式。支持取值如下： cbr ：（默认）恒定码率模式。仅当 video.codec 参数取值为 h264 时支持。编码器会尝试使音频流的每一秒都严格保持在 bitrate_kbps 参数设定的码率。这使得文件大小可以被精确预测，适合对带宽稳定性要求高的流式传输场景。 cae：自适应码率模式（仅 audio.codec 为 aac 时支持）。编码器会根据音频内容的复杂度动态调整瞬时码率，但会确保整个文件的平均码率接近 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 时生效。

请求示例

以下示例演示了如何提交一个极智超清转码任务：

将视频封装为 MP4 格式。

视频编码采用 h265，使用 crf 模式，CRF 值为 23，并限制长边为 1920 像素。

音频码率设置为 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 字段将包含以下内容。

参数	类型	描述
video_url	String	输出视频地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	视频时长，单位为秒。
resolution	String	转码后视频的分辨率。可能取值包括： "240p", "360p", "480p", "540p", "720p", "1080p", "2k", "4k"。
video_codec	String	视频编码格式，例如 h264 或 h265。

最终的完整任务信息示例：

AI MediaKit