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

说明

如需了解完整的使用流程和应用示例，请参阅极智超清。

## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`video_url` |String |是 |`https://example-video.com/input.mov` |待转码的视频 URL。

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

* **支持格式**：mp4, mov, mkv, flv, ts, avi, wmv 等主流视频格式 | |`container_format` |String |是 |`MP4` |输出视频的封装格式。支持取值如下：

* `MP4` (默认)

* `FLV`

* `MPEGTS` | |`video` |Object |是 |`-` |视频转码参数配置。详见下文 [Video 对象（视频转码参数）](https://docs.volcengine.com/docs/6448/2515358#WdNeUS3ZdB)。 | |`audio` |Object |否 |`-` |音频转码参数配置。如不传入此对象，则音频将采用默认参数进行转码（编码格式为 aac，其余参数跟随源文件）。详见下文[Audio 对象（音频转码参数）](https://docs.volcengine.com/docs/6448/2515358#EBowCWTSNG)。 | |`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 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_custom_callback_args` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://docs.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |`https://example.com/callback` |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://docs.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://docs.volcengine.com/docs/6448/2519520)。 | #### 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。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/martencode-video' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_video.mp4", "container_format": "MP4", "video": { "codec": "h265", "scale_type": 1, "scale_long": 1920, "bitrate_mode": "crf", "bitrate_crf": 23, "bitrate_kbps": 4000 }, "audio": { "codec": "aac", "sample_rate": 44100, "bitrate_mode": "cbr", "bitrate_kbps": 192 } }' ``` ## 响应说明调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。 ### 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |`success` |Boolean |任务是否成功提交。

* `true`：任务已成功提交到后台处理队列。

* `false`：请求存在错误，任务提交失败。请检查 `error` 字段以获取详细信息。 | |`task_id` |String |任务的唯一标识符。仅在 `success` 为 `true` 时返回有效值。您可以使用此 ID 来查询任务状态和结果。 | |`request_id` |String |本次 API 请求的唯一标识符，可用于问题排查。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 [Error 对象](https://docs.volcengine.com/docs/6448/2515358#2db583fb)。 | #### Error 对象 |**参数** |**类型** |**描述** | |---|---|---| |`code` |String |具体的错误码。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)， | |`type` |String |错误的宏观类型。例如 `BadRequest`。 | |`message` |String |对错误的详细描述，可用于开发调试。 | |`param` |String |（可选）指出导致错误的具体参数。 | ### 响应示例 #### 成功响应 ```JSON { "success": true, "task_id": "amk-tool-martencode-video-123456789", "request_id": "20240522180000ABCDEFG12345" } ``` #### 失败响应 ```JSON { "success": false, "task_id": "", "request_id": "20240522180500XYZW12345", "error": { "code": "InvalidParameter", "message": "The parameter 'video_url' is missing or invalid.", "type": "BadRequest" } } ``` ## 异步任务结果极智超清是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果： * **方法一（轮询查询）：** 使用提交任务时获取的 `task_id`，定期调用[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532)，直到 `status` 字段变为 `completed` 或 `failed`。 * **方法二（事件回调）：** 在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 `callback_url` 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅[事件回调](https://docs.volcengine.com/docs/6448/2288701)。当任务成功完成后，您获取到的任务信息中的 `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`。 | 最终的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-martencode-video-123456789", "request_id": "20240522180000ABCDEFG12345", "result": { "video_url": "https://example.volcvideo.com/martencode_output.mp4?auth_key=...", "duration": 125.5, "resolution": "1080p", "video_codec": "h265" }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ```