`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/enhance-video-smoothness` 本 API 用于提交一个异步的视频流畅度提升任务。工具基于视频画面与运动信息，自动识别运动节奏突变、重复帧等卡顿问题，并通过光流、运动矢量等算法生成中间帧、删除重复帧，在异常片段进行智能修复，还原连续、自然的运动画面。

说明

默认情况下，工具将同时开启周期性卡顿检测和重复帧检测，并对检测到的问题自动修复，直接返回修复后的视频。当您希望关闭修复（即只检测不修复）或进行人工指定插帧等进阶操作时，需要显式传入periodic_stutter_detect 和 duplicate_frame_detect 这两个配置对象。如需了解完整的使用流程和应用示例，请参阅视频流畅度提升。

## 请求参数 ### 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.com/your_video.mp4` |待检测和修复的视频源 URL。

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

* 格式：`mp4`, `avi`, `mov`

* 分辨率：最高支持 4K。

* 时长：执行修复时，视频时长不能超过 35 秒；仅执行检测时，无时长限制。 | |`periodic_stutter_detect` |Object |否 |`{"periodic_stutter_repair": true, "align_source_fps": false}` |周期性卡顿检测与修复配置。如不传此对象，默认执行周期性卡顿检测并修复。详见下文 [Periodic stutter detect 对象](https://docs.volcengine.com/docs/6448/2702305#periodic-stutter-detect-%E5%AF%B9%E8%B1%A1)。 | |`duplicate_frame_detect` |Object |否 |`{"duplicate_frame_repair": true}` |重复帧检测与修复配置。如不传此对象，默认执行重复帧检测并修复。详见下文 [Duplicate frame detect 对象](https://docs.volcengine.com/docs/6448/2702305#duplicate-frame-detect-%E5%AF%B9%E8%B1%A1)。 | |`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 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_unique_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)。 | #### Periodic stutter detect 对象 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |`periodic_stutter_repair` |Boolean |否 |`true` |是否修复检测到的周期性卡顿。默认值为 `true`。

* `true`：检测并修复周期性卡顿。

* `false`：仅检测，不修复。 | |`insert_frame_indices` |Array of Integer |否 |`[80, 120]` |人工指定插帧位置的数组，用于补充算法可能漏检的卡顿点。仅在 `periodic_stutter_repair` 为 `true` 时生效。数组元素为帧号（从 0 开始），为不小于 0 的整数且不可重复，至少包含 1 个元素。例如 `[80, 120]` 表示在第 80 帧与第 81 帧之间、第 120 帧与第 121 帧之间各插入一帧。 | |`align_source_fps` |Boolean |否 |`false` |是否使修复后视频的帧率与原视频保持一致。默认值为 `false`。

* `false`（默认）：修复效果优先，输出视频的帧率和总帧数可能因插帧而增加。

* `true`：在插入补偿帧的同时会删除等量的低变化帧，使总帧数与时长保持不变，适合对帧率一致性有要求的场景。 | #### Duplicate frame detect 对象 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |`duplicate_frame_repair` |Boolean |否 |`true` |是否修复检测到的重复帧。默认值为 `true`。

* `true`：检测并删除重复帧。

* `false`：仅检测，不修复。 | ## 请求示例以下示例演示了如何对一段视频执行默认的卡顿检测与修复。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/enhance-video-smoothness' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_video.mp4", "periodic_stutter_detect": { "periodic_stutter_repair": true, "align_source_fps": false }, "duplicate_frame_detect": { "duplicate_frame_repair": true } }' ``` ## 响应说明调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。 ### 响应参数 |**参数** |**类型** |**描述** | |---|---|---| |`success` |Boolean |任务是否成功提交。

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

* `false`：请求存在错误，任务提交失败。请检查 `error` 字段以获取详细信息。 | |`task_id` |String |任务的唯一标识符。仅在 `success` 为 `true` 时返回有效值。您可以使用此 ID 来查询任务状态和结果。 | |`request_id` |String |本次 API 请求的唯一标识符，可用于问题排查。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 Error 对象。 | #### Error 对象 |**参数** |**类型** |**描述** | |---|---|---| |`code` |String |具体的错误码。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)。 | |`type` |String |错误的宏观类型。例如 `BadRequest`。 | |`message` |String |对错误的详细描述，可用于开发调试。 | |`param` |String |（可选）指出导致错误的具体参数。 | ### 响应示例 #### 成功响应 ```JSON { "success": true, "task_id": "amk-tool-enhance-video-smoothness-123456789", "request_id": "20240523100000ABCDEFG12345" } ``` #### 失败响应 ```JSON { "success": false, "task_id": "", "request_id": "20240523101000WXYZ54321", "error": { "code": "InvalidParameter", "message": "The 'video_url' parameter is required", "param": "video_url", "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 |输入视频时长，单位为秒，用于计量计费。 | |`inserted_frames_detail` |Object |周期性卡顿检测的插帧明细。只要开启了周期性卡顿检测（默认开启），无论是否执行修复、修复是否因效果评估未通过而跳过，均会返回此对象。包含以下字段：

* `inserted_frame_count`（Integer）：基于原始视频检测判定需要因周期性卡顿而插入的帧数（不包含通过 `insert_frame_indices` 人工指定的帧数）。该数值为检测结果，不代表实际已完成插帧。 | |`duplicate_frames_detail` |*Object* |重复帧检测明细。只要开启了重复帧检测（默认开启），无论是否执行修复、修复是否因效果评估未通过而跳过，均会返回此对象。包含以下字段：

* `duplicate_frame_count`（Integer）：被算法判定为与前一帧重复的帧数。该数值的统计基准取决于周期性卡顿修复是否执行：

* 若周期性修复成功执行，重复帧检测基于修复后的中间产物。

* 若未开启或因效果评估未通过而跳过，则基于原始视频。 | 以下是一个视频流畅度提升任务执行完成后的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-enhance-video-smoothness-123456789", "request_id": "20240523100000ABCDEFG12345", "status": "completed", "result": { "video_url": "https://example.com/output/repaired.mp4?sign=...", "duration": 16.0, "inserted_frames_detail": { "inserted_frame_count": 24 }, "duplicate_frames_detail": { "duplicate_frame_count": 8 } }, "expires_at": 1777531298, "created_at": 1777358413, "finished_at": 1777359999 } ```