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

本 API 用于提交一个异步的视频画质增强任务。它利用 AI 算法对输入视频进行分析，并智能执行一系列优化操作，包括但不限于视频去噪、色彩增强、清晰度提升、瑕疵修复和超分辨率。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/source.mp4	待增强的视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。文件大小：建议单个输入文件大小不超过 10 GB。输入视频分辨率：最高支持 2K。具体规格要求：短边范围：[360,1440] 长边范围：[360,2560]
tool_version	String	否	professional	工具版本，影响增强算法的强度、适用场景与计费。 standard：（默认值）标准版。兼顾处理速度与视频画质，内置高频使用的 10 余种增强算法，覆盖主流播放平台画质要求。适用于视频分发场景的画质增强。 professional：专业版。极致画质增强，内置 30 余种深度 AI 增强算法，保障镜头级画质效果。适用于影视级视频制作。详细说明与效果对比，请参见版本说明及效果章节。
scene	String	否	aigc	画质增强场景，仅在 tool_version 为 standard 时生效。用于选择一个针对特定业务场景的预设画质增强模板。可选值： common：（默认值）通用模板。 ugc：UGC 短视频场景。 short_series：短剧场景。 aigc：AIGC 内容场景。 old_film：老片修复场景。各场景的详细说明与效果对比，请参见场景说明及效果章节。
enhance_style	String	否	natural	画质增强风格。标准版（tool_version 为 standard）与专业版（tool_version 为 professional）均支持。可选值： hd：（默认）高清。增强强度适中，画面锐利清晰。 natural：自然。降低画质增强强度，锐化痕迹更少，画面观感更自然。详细说明与效果对比，请参见配置增强风格章节。
resolution	String	否	1080p	目标分辨率档位。您可以使用此参数将视频超分到指定规格。支持： 240p 360p 480p 540p 720p 1080p 2k 4k 6k 8k 注意：此参数与 resolution_limit 互斥，不可同时配置。
resolution_limit	Integer	否	1920	目标分辨率的短边像素限制，取值范围 [128, 4320]。系统将根据此值，在保持原视频宽高比的前提下，等比缩放到该限制值。注意：此参数与 resolution 互斥，不可同时配置。
bitrate_level	String	否	medium	目标码率档位，用于控制输出视频的平均码率。该参数将影响视频的视觉质量和最终的文件体积。默认为 medium。 low：低码率 medium：中码率（推荐） high：高码率注意：实际输出码率还会结合目标分辨率与帧率自动换算，不同档位对应的目标输出码率，请参见码率参考表。如需精确指定码率，请使用 bitrate 参数。
bitrate	Integer	否	8000	目标平均码率，单位为 kbps，取值范围 [10, 150000]。不填时按 bitrate_level 结合分辨率与帧率自动换算。当同时指定 bitrate 与 bitrate_level 时，仅 bitrate 生效。
fps	Number	否	60	目标帧率，单位为 fps。若未指定 fps 参数，输出视频将保持与原始片源一致的帧率。取值范围 [15, 120]。建议不超过原片的 4 倍。
bit_depth	Integer	否	10	目标色深（也称为位深），仅专业版（tool_version 为 professional）支持。取值如下： 8：（默认值）8 bit 位深，每个颜色通道有 2⁸（即 256）个亮度等级。支持 h264、h265 编码。 10：10 bit 位深，每个颜色通道有 2¹⁰（即 1024）个亮度等级。支持 h265、prores 编码。 12：12 bit 位深，每个颜色通道有 2¹²（即 4096）个亮度等级。支持 h265 编码。 16：16 bit 位深，每个颜色通道有 2¹⁶（即 65536）个亮度等级。支持 ffv1、exr 编码。注意：请确保输入视频时长不超过 40 秒。此档位下，码率由系统自动决定，bitrate、bitrate_level 参数均不生效。 16 bit 色深任务为单任务串行处理，即只能单一任务处理完成后，再开始新任务处理，因此处理时间可能较长。详细说明，请见配置输出色深（仅专业版）。
codec	String	否	h265	视频编码格式，仅专业版（tool_version 为 professional）支持。指定 codec 时必须同时指定 bit_depth，且两者需为合法组合，详见色深、编码格式与封装格式组合。若未指定 codec，系统将按 bit_depth 自动选择相应编码：8 的默认编码为 h264；10 和 12 的默认编码为 h265；16 的默认编码为 ffv1。支持的编码格式如下： h264 h265 prores ffv1 exr 注意：prores、ffv1、exr 编码不支持指定码率，此时 bitrate、bitrate_level 参数均不生效。
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_131	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_unique_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何为一个 UGC 短视频提交专业版画质增强任务，并指定输出分辨率为 1080p，帧率为 60fps。

响应说明

任务提交后，接口会立即返回以下 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 字段将包含以下内容。

参数	类型	示例	描述
video_url	String	https://example.volcvideo.com/output.mp4?auth_key=...	增强后的视频文件下载地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	120.5	输出视频的总时长（单位：秒）。
resolution	String	1080p	输出视频的分辨率。
fps	Number	60	输出视频的帧率。
tool_version	String	professional	任务实际使用的工具版本。

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

错误处理

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

附录

码率参考表

下表列出了在不同分辨率和帧率组合下，当 bitrate_level 参数分别设置为 low（低码率）、medium（中码率）和 high（高码率）时，所对应的目标输出码率。请注意，为保证各种场景下的画质稳定性，系统会根据视频内容的复杂度动态调整码率。因此，实际输出码率通常会在表中所列目标值的 0.8 倍至 1.5 倍范围内浮动。

输出视频分辨率	输出视频帧率（fps）	低码率（Mbps）	中码率（Mbps）	高码率（Mbps）
240p	[15,30]	0.3	0.45	0.6
		(30,60]	0.65	0.9	1.2
		(60,120]	1.5	2.2	2.8
360p	[15,30]	0.6	0.85	1.2
		(30,60]	1	1.5	2
		(60,120]	1.7	2.5	3.2
480p	[15,30]	1.2	1.8	2.3
		(30,60]	2.1	3	3.9
		(60,120]	3.5	5	6.5
540p	[15,30]	1.7	2.5	3.2
		(30,60]	2.8	4	5.2
		(60,120]	4.2	6	7.8
720p	[15,30]	2.8	4	5.2
		(30,60]	5.6	8	10
		(60,120]	8.4	12	15
1080p	[15,30]	5	7	9
		(30,60]	10	14	18
		(60,120]	15	22	28
2K	[15,30]	10	15	20
		(30,60]	17	24	32
		(60,120]	28	40	52
4K	[15,30]	21	30	39
		(30,60]	32	45	58
		(60,120]	53	75	100
8K	[15,30]	42	60	78
		(30,60]	63	90	120
		(60,120]	84	120	150

AI MediaKit