`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/vibe-editing` 本 API 用于提交一个异步的智能剪辑（vibe editing）任务。您可以通过传入图片、视频、音频、字幕素材 URL 与自然语言指令，让系统自动完成意图理解、参数转换、多轨剪辑、云端渲染与成片导出。 * **获取任务结果**：任务提交成功后，您需要保存返回的 `task_id`，并通过轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或配置[事件回调](https://www.volcengine.com/docs/6448/2288701)获取最终结果。 * **开发指南**：如需了解完整的使用流程和应用示例，请参阅[模式 1：直接生成](https://www.volcengine.com/docs/6448/2549864#2a86077e)。 * **前置条件（开通跨服务授权）** ：智能剪辑工具会在剪辑过程中根据自然语言意图调用其他 AI MediaKit 工具以及剪辑合成工具完成最终成片。因此在首次调用本 API 前，您必须先在 AI MediaKit 控制台[基础配置 > 授权管理](https://console.volcengine.com/imp/ai-mediakit/settings?tab=authorization&projectName=default)页面，为 AI MediaKit 授予访问您 **IMP 智能处理**资源的权限。否则，任务将因无权限访问而失败。同一账号下只需授权一次，后续调用无需重复操作。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_MediaKit_API_Key}` |格式为 `Bearer {Your_MediaKit_API_Key}`。请参考[基础概念及准备工作](https://www.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |描述 | |---|---|---|---| |`content` |Array |是 |输入内容列表，支持多模态混排：`text`（自然语言指令）、`image_url`、`video_url`、`audio_url`、`subtitle_url` 五种元素。至少需要 1 项。数组顺序会影响 AI 理解上下文，建议将指令文本放在首位或末位。详见下文 [content 结构](https://www.volcengine.com/docs/6448/2563056#content-%E5%85%83%E7%B4%A0%E7%BB%93%E6%9E%84)。 | |`output` |Object |否 |输出配置。详见下文 [output 结构](https://www.volcengine.com/docs/6448/2563056#output-%E7%BB%93%E6%9E%84)。 | |`client_token` |String |否 |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://www.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://www.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://www.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://www.volcengine.com/docs/6448/2519520)。 | #### content 结构 |参数 |类型 |是否必选 |描述 | |---|---|---|---| |`type` |String |是 |内容类型。可选值：`text`、`image_url`、`video_url`、`audio_url`、`subtitle_url`。 | |`text` |String |否 |文本指令，仅当 `type=text` 时填写。使用自然语言描述剪辑目标，例如 “将视频 1 和视频 2 拼接在一起，添加轻音乐 BGM 并在末尾加淡出”。 | |`image_url` |Object |否 |图片素材 URL 对象，仅当 `type=image_url` 时填写。仅支持公网可访问的 HTTP/HTTPS URL。 | |`video_url` |Object |否 |视频素材 URL 对象，仅当 `type=video_url` 时填写。仅支持公网可访问的 HTTP/HTTPS URL。 | |`audio_url` |Object |否 |音频素材 URL 对象，仅当 `type=audio_url` 时填写。仅支持公网可访问的 HTTP/HTTPS URL。 | |`subtitle_url` |Object |否 |字幕素材 URL 对象，仅当 `type=subtitle_url` 时填写。仅支持公网可访问的 HTTP/HTTPS URL。 | #### output 结构 |参数 |类型 |是否必选 |描述 | |---|---|---|---| |`type` |String |否 |输出产物类型。可选值：

* `video`：（默认）输出视频。

* `audio`：仅输出音频。 | |`resolution` |String |否 |视频输出分辨率，仅当 `type=video` 时生效。

* 支持预设档位 `360p`、`480p`、`720p`、`1080p`、`2k`、`4k`

* 也支持宽高格式（如 `1920x1080`）。宽和高的取值范围均为 [160,8192]。

未填写时由系统根据输入素材自动决策。 | |`format` |String |否 |输出封装格式。可选值：`mp4`（视频）、`mp3`（音频）。未填写时按 `type` 自动选择。 | |`fps` |Integer |否 |视频输出帧率，仅当 `type=video` 时生效。取值范围 `[15,60]`，默认 `25`。 | |`meta` |Object |否 |可选输出元信息。详见下文 [meta 结构](https://www.volcengine.com/docs/6448/2563056#802db13b)。 | #### meta 结构 |**参数** |**类型** |**是否必选** |**描述** | |---|---|---|---| |aigc |String |否 |人工智能生成合成内容（AIGC）标识。该字段需传入一个 **JSON 字符串**，用于在视频元数据中嵌入合规信息。其内部结构请参考本文档[附录：AIGC 元数据结构](https://www.volcengine.com/docs/6448/2563056#93a2533d)。 | ## 请求示例以下示例演示了如何提交一个智能剪辑任务：将 2 段视频与 1 段音频交给 AI，按自然语言指令生成一段 720p、mp4、25fps 的合成视频，并为其添加 AIGC 合规标识。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/vibe-editing' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "content": [ { "type": "text", "text": "把两段视频按顺序拼接，加入这段 BGM 并将整体音量调整为 -6dB，末尾做 1 秒淡出。" }, { "type": "video_url", "video_url": { "url": "https://example.com/clip_a.mp4" } }, { "type": "video_url", "video_url": { "url": "https://example.com/clip_b.mp4" } }, { "type": "audio_url", "audio_url": { "url": "https://example.com/bgm.mp3" } } ], "output": { "type": "video", "resolution": "720p", "format": "mp4", "fps": 25, "meta": { "aigc": "{\"Label\":\"1\",\"ContentProducer\":\"AI MediaKit\",\"ProduceID\":\"your_custom_id_123\"}" } } }' ``` ## 响应说明 ### 任务提交成功响应 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否提交成功。

• `true`：成功。

• `false`：失败。更多信息请查看[错误处理](https://www.volcengine.com/docs/6448/2563056#4dc49ed1)。 | |`task_id` |String |任务的唯一标识，用于后续查询任务状态和结果。 | |`request_id` |String |本次请求的唯一标识，可用于问题排查。 | **示例：** ```JSON { "success": true, "task_id": "amk-tool-vibe-editing-123456789", "request_id": "20260701150000ABCDEFG12345" } ``` ### 异步任务结果任务处理完成后，通过[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或[事件回调](https://www.volcengine.com/docs/6448/2288701)获取的 `result` 字段将包含以下内容。 |参数 |类型 |描述 | |---|---|---| |`artifacts` |Array |输出产物列表，每项对应一份产物（视频或音频）。详见下文[artifact 结构](https://www.volcengine.com/docs/6448/2563056#artifact-%E7%BB%93%E6%9E%84)。 | #### artifact 结构 |参数 |类型 |描述 | |---|---|---| |`operation` |String |产物对应的合成操作类型。当前固定为 `synthesize`。 | |`type` |String |产物类型。可选值：`video`、`audio`。 | |`url` |String |产物下载 URL。该地址的有效期为 **24 小时**，请务必及时保存产物。 | |`duration` |Number |该项产物时长（单位：秒）。 | |`description` |String |产物描述，由系统根据本次剪辑意图生成。 | 示例： ```JSON { "success": true, "task_id": "amk-tool-vibe-editing-123456789", "request_id": "20260701150000ABCDEFG12345", "result": { "artifacts": [ { "operation": "synthesize", "type": "video", "url": "https://example.volcvideo.com/vibe_editing_output.mp4?auth_key=...", "duration": 42.5, "description": "拼接 clip_a 与 clip_b，叠加 BGM，整体 -6dB，末尾淡出 1s。" } ] }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ``` ## 错误处理当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应，详见[错误码](https://www.volcengine.com/docs/6448/2300662)。示例如下： ```JSON { "success": false, "task_id": "", "request_id": "20260701150500XYZW12345", "error": { "code": "InvalidParameter", "message": "The field `content` must not be empty.", "param": "content", "type": "BadRequest" } } ``` ## 附录：AIGC 元数据结构根据国家广播电视总局发布的《生成式人工智能内容标识规范》，当您使用智能剪辑 API 生成内容时，可以通过 meta.aigc 参数为产物添加 AIGC 标识。该参数接收一个 JSON 字符串，其内部结构应遵循下表规范： |**要素** |**要素名称** |**类型** |**取值** | |---|---|---|---| |Label |生成合成标签 |String |* 属于人工智能合成内容的，取值为 “1”

* 可能为人工智能合成内容的，取值为 “2”

* 疑似为人工智能合成内容的，取值为 “3” | |ContentProducer |生成合成服务提供者 |String |生成合成服务提供者的名称或编码 | |ProduceID |内容制作编号 |String |生成合成服务提供者对该内容的唯一编号 | |ReservedCode1 |预留字段 1 |String |用于生成合成服务提供者自主开展安全防护，保护内容、标识完整性的信息 | |ContentPropagator |内容传播服务提供者 |String |内容传播服务提供者的名称或编码 | |PropagateID |内容传播编号 |String |传播服务提供者对该内容的唯一编号 | |ReservedCode2 |预留字段 2 |String |内容传播服务提供者自主开展安全防护，保护内容、标识完整性的信息 |