画质增强 API 文档

本文档用于给用户调用已配置好的 VolcMediaKit 渠道。Apifox 可直接导入：

docs/openapi/volcmediakit-video-enhancement.openapi.json

官方参考文档：

提交画质增强（标准版/专业版）任务 API

提交画质增强（极速版）任务 API

结论

用户只调用 new-api 的标准异步视频接口：

POST /v1/videos
GET  /v1/videos/{task_id}

请求头使用 new-api Token：

后台渠道要求

模型：
volc-enhance-video-fast,
volc-enhance-video-standard,
volc-enhance-video-professional

模型说明

模型	火山能力	说明
`volc-enhance-video-fast`	极速版	速度优先，不支持 `tool_version` 和 `scene`
`volc-enhance-video-standard`	标准版	固定 `tool_version=standard`，支持 `scene`
`volc-enhance-video-professional`	专业版	固定 `tool_version=professional`，不支持 `scene`

创建任务

请求参数

字段	类型	必填	说明
`model`	string	是	三个 VolcMediaKit 模型之一，也可使用后台模型映射别名
`video_url`	string	是	待增强的视频 URL，必须是公网可访问的 HTTP/HTTPS 地址；支持 `mp4`、`flv`、`ts`、`avi`、`mov`、`wmv`、`mkv` 等主流格式；建议单文件不超过 10GB，输入视频最高 2K
`resolution`	string	否	目标分辨率档位，用于将视频超分到指定规格；支持 `240p`、`360p`、`480p`、`540p`、`720p`、`1080p`、`2k`、`4k`；与 `resolution_limit` 互斥
`resolution_limit`	integer	否	目标分辨率的短边像素限制，取值范围 `[128,2160]`；系统会保持原视频宽高比并按短边等比缩放；与 `resolution` 互斥
`bitrate_level`	string	否	目标码率档位，用于控制输出视频平均码率，影响画质和最终文件体积；支持 `low`、`medium`、`high`，默认 `medium`
`fps`	number	否	目标帧率，单位 fps；取值范围 `[15,120]`；不传时保持原片帧率，建议不超过原片 4 倍
`scene`	string	否	仅标准版支持的画质增强场景模板；支持 `common`、`ugc`、`short_series`、`aigc`、`old_film`，默认 `common`
`client_token`	string	否	用户请求凭证，用于幂等控制；大小写敏感，最多 64 个 ASCII 可打印字符
`callback_args`	string	否	自定义回调透传参数，火山会在任务完成回调中原样返回；当前 new-api 不接火山回调，仅建议预留业务关联信息，最多 512 字节
`queue_id`	string	否	火山队列 ID；不传时由火山使用默认队列
`callback_url`	string	否	火山原生支持任务级回调地址，但当前 new-api 不接火山回调；传入会返回 400，请使用查询接口轮询

参数取值说明

`bitrate_level`

bitrate_level 不是“枚举字段本身”的含义，而是目标输出码率档位。它用于控制输出视频的平均码率，码率越高通常画质越稳、文件越大；码率越低文件越小，但复杂画面更容易损失细节。

取值	简易说明	适合场景
`low`	低码率，文件体积更小，画质保真更弱	预览、低成本分发、对文件体积敏感
`medium`	中码率，火山默认值和推荐平衡档	常规分发、默认选择
`high`	高码率，目标输出码率更高，文件体积更大	高质量交付、细节较多或二次剪辑素材

火山文档说明，不同分辨率和帧率组合会对应不同目标输出码率，实际输出码率还会根据视频内容复杂度动态调整。已知限制：如果同时设置 fps 和 bitrate_level，bitrate_level 可能不生效。

`scene`

scene 只对 volc-enhance-video-standard 生效，用来选择面向具体业务场景的预设画质增强模板。

取值	简易说明
`common`	通用模板，默认值
`ugc`	UGC 短视频场景
`short_series`	短剧场景
`aigc`	AIGC 内容场景
`old_film`	老片修复场景

极速版和专业版都不支持 scene；传入会返回参数错误。

专业版示例

成功响应

{
  "id": "task_01JY6N8Q2R8X5BTQ7VM3W9K2W1",
  "task_id": "task_01JY6N8Q2R8X5BTQ7VM3W9K2W1",
  "object": "video",
  "model": "volc-enhance-video-professional",
  "status": "queued",
  "progress": 0,
  "created_at": 1781510400
}

查询任务

示例

完成响应

{
  "id": "task_01JY6N8Q2R8X5BTQ7VM3W9K2W1",
  "task_id": "task_01JY6N8Q2R8X5BTQ7VM3W9K2W1",
  "object": "video",
  "model": "volc-enhance-video-professional",
  "status": "completed",
  "progress": 100,
  "created_at": 1781510400,
  "completed_at": 1781510520,
  "expires_at": 1781596920,
  "metadata": {
    "url": "https://example.volcvideo.com/enhanced_output.mp4?auth_key=...",
    "duration": 120.5,
    "resolution": "1080p",
    "fps": 60,
    "tool_version": "professional"
  }
}

任务必须已经 completed。火山结果短链有效期有限，建议完成后尽快下载或自行转存。

常见错误

缺少 video_url

{
  "error": {
    "message": "video_url is required",
    "type": "invalid_request_error",
    "code": "missing_video_url"
  }
}

resolution 与 resolution_limit 冲突

{
  "error": {
    "message": "resolution and resolution_limit cannot be configured at the same time",
    "type": "invalid_request_error",
    "code": "invalid_resolution"
  }
}

专业版传入 scene

{
  "error": {
    "message": "scene is only supported by volc-enhance-video-standard",
    "type": "invalid_request_error",
    "code": "invalid_scene"
  }
}

callback_url 不支持

{
  "error": {
    "message": "callback_url is not supported; use /v1/videos/{task_id} polling",
    "type": "invalid_request_error",
    "code": "invalid_callback_url"
  }
}

画质增强 API 文档

结论#

后台渠道要求#

模型说明#

创建任务#

请求参数#

参数取值说明#

bitrate_level#

scene#

专业版示例#

成功响应#

查询任务#

示例#

完成响应#

常见错误#

缺少 video_url#

resolution 与 resolution_limit 冲突#

专业版传入 scene#

callback_url 不支持#

结论