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

本 API 用于提交一个同步的图像画质增强任务，基于图像内容理解进行智能决策，全方位提升图片的分辨率、清晰度与色彩表现。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/source.jpg	待增强的图像 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。图像输入分辨率：不同 tool_version 支持的输入和输出尺寸范围有所不同，详情请参考图像画质增强开发指南中的“模型版本说明”及“性能与限制”章节。图像宽高比限制：对于大模型增强版（tool_version 为 max），输入图像的“长边/短边”之比不得超过 32。文件大小：单张图片不得超过 10 MB。支持格式：支持 .png、.jpg、.jpeg 和 .webp 等常见主流图像格式。
tool_version	String	否	professional	画质增强选用的模型版本。不同版本在效果、处理范围、价格上有所差异。 standard：（默认）标准版。平衡处理速度、码率增长与画质效果。 professional：专业版。发丝级画质增强，在平衡保真度的前提下适当补充自然纹理细节，显著提升低质图像的画面清晰度与色彩表现。 max：大模型增强版。基于生成式大模型，在尝试保证全局结构和语义一致性的前提下，修复图像画质、生成自然纹理细节，针对低质图像可显著提升图像细节丰富度和清晰度。说明更多关于各版本的说明、效果对比、适用场景、分辨率限制，详见图像画质增强开发指南中的“模型版本说明”及“性能与限制”章节。
multiple	Number	否	2.5	图像处理后较原图的放大倍数，支持 2 位小数。标准版（tool_version 取值为 standard）：取值范围为 [1, 8]。专业版（tool_version 取值为 professional)：取值范围为 [1, 30]。大模型增强版（tool_version 取值为 max)：取值范围为 [1, 30]。最终生成图像的宽度和高度不能超过所选模型版本支持的最大分辨率。
target_width	Integer	否	1920	图像处理后的目标宽度，单位为 px。标准版（tool_version 取值为 standard）：取值范围为 [原图宽度, 6144]。且最终放大倍数不能超过 8 倍。专业版（tool_version 取值为 professional)：取值范围为 [64, 10240]。大模型增强版（tool_version 取值为 max)：取值范围为 [64, 10240]。说明 target_height 通常与 target_width 配合使用，或单独设置以保持原图宽高比。对于大模型增强版（tool_version 为 max），建议将输出分辨率的目标尺寸（target_width、target_height）控制在 8000x8000 以内，以避免处理超大分辨率图像时发生超时。
target_height	Integer	否	1080	图像处理后的目标高度，单位为 px。标准版（tool_version 取值为 standard）：取值范围为 [原图高度, 6144]。且最终放大倍数不能超过 8 倍。专业版（tool_version 取值为 professional)：取值范围为 [64, 10240]。大模型增强版（tool_version 取值为 max)：取值范围为 [64, 10240]。说明 target_height 通常与 target_width 配合使用，或单独设置以保持原图宽高比
enable_correct_color	Boolean	否	true	是否开启色彩校正，仅当 tool_version 为 max 时生效，取值如下： true（默认）：开启色彩校正。系统将尽量保持增强后图片的色彩与原图一致。 false：关闭色彩校正。若您发现开启色彩校正后结果出现过度锐化，建议关闭。
generative_enhance_mode	String	否	generative_first	生成式增强策略，用于控制模型在“忠于原图”和“创造性修复”之间的平衡点。此参数仅在 tool_version 为 professional 或 max 时生效。支持取值如下： fidelity_first：保真度优先。此模式下，模型会更侧重于保留和增强图像的既有细节（如人物特征、原始纹理），尽可能减少对原始内容的改动。适用场景：当您需要高度还原细节时，如处理人像、产品图、文字截图等。 generative_first：（默认）生成度优先。此模式下，模型会在保留原图结构的基础上智能生成更丰富、更自然的纹理细节，以达到最佳的主观视觉效果。适用场景：修复严重压缩或模糊的低质量图像，或当您希望获得最大程度的清晰度和细节感，并可以接受一定程度的细节再创作时。如需了解两种模式的效果对比，请参阅选择生成式增强策略：保真度优先 vs 生成度优先。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何为一个图片提交“专业版”图像画质增强任务，并指定放大倍率为 2 倍，输出格式为 JPEG。

响应说明

这是一个同步接口，处理结果将直接在本接口的响应体中返回。

响应参数

参数	类型	描述
success	Boolean	任务是否成功。 true：成功。请查看 result 字段以获取任务结果。 false：失败。请查看 error 字段以获取详细错误信息。
result	Object	包含图像处理结果的对象，仅在 success 为 true 时返回。详见下文 Result 对象。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。
task_id	String	任务的唯一标识。
task_type	String	任务类型。
request_id	String	本次 API 请求的唯一标识，可用于问题排查。
expires_at	Integer	任务结果的过期时间戳（Unix Time，单位：秒）。仅当任务成功且有结果时返回。
queue_id	String	任务提交的目标队列 ID。

Result 对象

参数	类型	描述
image_url	String	增强后的图片文件下载地址。该地址的有效期为 24 小时，请务必及时保存产物。
image_size	Integer	生成图像的大小，单位为字节。
image_format	String	生成图像的格式。当请求参数 tool_version 为 standard（标准版）时，输出格式固定为 png。当请求参数 tool_version 为 professional（专业版）或 max（大模型增强版）时，输出格式与输入图像的格式保持一致。
image_width	Integer	生成图像的宽度，单位为 px。
image_height	Integer	生成图像的高度，单位为 px。

Error 对象

参数	类型	描述
code	String	具体的错误码，用于程序化识别错误类型。例如：InvalidParameter。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如：BadRequest。
message	String	对错误的详细描述，可用于开发调试。

响应示例

成功响应示例：

失败响应示例：

AI MediaKit