`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/apply-camera-motion` 本 API 用于提交一个异步的视频添加运镜任务，对输入视频在指定时间段内添加一种运镜特效。输出为 MP4 格式，分辨率默认对齐原片。此功能常用于素材二次创作、营销片头、短剧动效等场景。

说明

如需了解完整的使用流程和应用示例，请参阅视频添加运镜。

## 请求参数 ### 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/source.mp4` |待处理的视频 URL。

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

* **支持格式**：`mp4`, `flv`, `ts`, `avi`, `mov`, `wmv`, `mkv` 等。

* **分辨率限制**：最高支持 1080p 分辨率。

* **时长限制**：不得超过 5 分钟。 | |`motion_style` |String |否 |`pan-zoom` |运镜风格。支持以下几种预设效果：

* `zoom`：（默认）视频缩放运镜

* `pan-zoom`：平移缩放运镜

* `orbit-360`：360 度旋转运镜

* `bounce`：镜头弹跳运镜

具体效果请参考[效果预览](https://docs.volcengine.com/docs/6448/2480266#lLofMpYRxL)。 | |`start_time` |Number |否 |`5` |运镜开始时间，默认为 `0`，表示从视频片头开始。仅传 `end_time` 时按 `0` 作为开始时间。支持设置为 2 位小数，单位：秒。不得小于 `0`。 | |`end_time` |Number |否 |`12.5` |运镜结束时间，默认为视频结尾。仅传 `start_time` 时会运镜到视频结尾；若填写值超过视频实际时长，将自动按视频时长处理。需大于 `start_time`。支持设置为 2 位小数，单位：秒。 | |`client_token` |String |否 |`your_unique_request_id_133` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_custom_callback_data` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](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)。 | ## 请求示例以下示例演示了如何为一个视频从第 5 秒到第 12.5 秒添加“平移缩放”（`pan-zoom`）运镜效果。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/apply-camera-motion' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/input_video.mp4", "motion_style": "pan-zoom", "start_time": 5, "end_time": 12.5 }' ``` ## 响应说明调用 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/2488165#91e08cf6)。 | #### Error 对象 |**参数** |**类型** |**描述** | |---|---|---| |`code` |String |具体的错误码。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)。 | |`type` |String |错误的宏观类型。例如 `BadRequest`。 | |`message` |String |对错误的详细描述，可用于开发调试。 | |`param` |String |（可选）指出导致错误的具体参数。 | ### 响应示例成功响应： ```JSON { "success": true, "task_id": "amk-tool-apply-camera-motion-123456789", "request_id": "20240521113000ABCDEFG12345" } ``` 失败响应： ```JSON { "success": false, "task_id": "", "request_id": "20240521113500XYZW54321", "error": { "code": "InvalidParameter", "message": "The parameter `video_url` 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 |`https://example.volcvideo.com/output.mp4?auth_key=...` |处理后的视频文件下载地址。文件格式为 MP4。地址类型根据请求时是否设置 `media_output_destination` 而不同：

* 默认情况（未设置 `media_output_destination`）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。

* 设置 `media_output_destination` 后：返回存储地址，格式为 `vod://<空间名>/<媒资ID>` 或 `tos://<桶名>/<对象Key>`。 | |`resolution` |String |`"1080p"` |输出视频的分辨率。 | |`duration` |Number |`125.8` |输出视频的总时长，单位为秒。 | 以下是一个任务执行完成后的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-apply-camera-motion-123456789", "task_type": "apply-camera-motion", "status": "completed", "result": { "video_url": "https://example.volcvideo.com/motion_output.mp4?auth_key=1774504841-...", "resolution": "1080p", "duration": 125.8 }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851, "request_id": "20240521113000ABCDEFG12345", "queue_id":"q2a028fa533b7fe6a25b018dccd6284" } ```