对于 AI MediaKit 的异步媒体处理任务（如音视频拼接、画质增强等），为了及时获取任务结果，建议您配置事件回调。当任务执行完成时，AI MediaKit 会主动向您指定的服务器地址发送 POST 请求，推送任务状态及结果数据。 ## 回调机制在接入回调通知前，请确保您的接收服务符合以下技术规范： * **请求方式**：AI MediaKit 会向您的回调地址发起 `POST` 请求。 * **响应要求**：您的服务器收到回调后，需在 5 秒内返回 `200` 状态码表示接收成功。 * **重试机制**：若回调失败（响应非 200 或连接超时），AI MediaKit 会发起最多 3 次重试，重试间隔依次为 5 秒、10 秒和 30 秒。若 3 次重试均失败，该通知将被丢弃。 * **安全说明**：当前版本暂不支持回调签名鉴权。请确保您的接收地址能够处理来自公网的 POST 请求，并建议在业务层根据 `task_id` 进行幂等校验。 ## 配置回调订阅 ### 步骤 1：勾选事件 1. 访问 AI MediaKit 控制台[基础配置页面](https://console.volcengine.com/imp/ai-mediakit/settings)。 2. 在**回调管理**页签下，单击**修改**，勾选需要接收的事件类型。当前仅支持[单任务执行完成事件](/docs/6448/2288701#98c8bf81)。 ### 步骤 2：配置接收地址在**回调订阅**区域，创建新的回调订阅，用于指定接收回调通知的地址和方式。具体步骤如下： 1. 单击**添加回调订阅**。 2. 配置以下信息： * **回调方式**：固定为 `http(s)`。 * **请求 Content\-Type**：选择回调请求的 Content\-Type。这将影响 AI MediaKit 服务向回调地址发送请求时请求体的数据格式。支持以下两种类型： * `application/json` * `application/octet-stream` * **接收地址**：（必填）输入用于接收回调通知的 URL 地址。必须以 `http://` 或 `https://` 开头。 3. 单击**确定**。修改配置后，生效时间为几分钟，请耐心等待。 ### 步骤 3：进行连通性测试 1. 在**回调订阅**列表中，单击操作列的**测试**。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/3743685c50a04b5fa937c54ca41e96d1 =600x) 2. 在**地址测试弹框**中勾选待测试事件，单击**确定**。 3. 在**回调记录**页签下等待回调完成，系统将自动弹出提示框，显示回调测试结果（成功或失败）。状态为**回调成功**，表示接收地址可用。 ## 单任务执行完成事件当您提交的异步任务（如视频拼接、画质增强等）执行完成（无论成功或失败）时，AI MediaKit 会向您配置的回调地址推送此事件。 ### 顶层字段说明 |**字段** |**类型** |**示例** |**描述** | |---|---|---|---| |RequestId |String |"2026032520..." |本次回调请求的唯一 ID。 | |Version |String |"1.0" |事件版本号，例如 "1.0"。 | |EventType |String |"AIMediaKitTaskComplete" |事件类型，固定为 `AIMediaKitTaskComplete`。 | |EventTime |String |"2026\-03\-25T12:44:34Z" |事件发生的 UTC 时间，格式为 YYYY\-MM\-DDTHH:mm:ssZ。 | |Data |Object |{...} |包含任务处理结果的核心数据对象。详见 [Data 对象字段说明](/docs/6448/2288701#d8af511a)。 | |TaskId |String |"amk_tool_..." |任务的唯一标识，与 `Data.TaskId` 的值相同。 | ### Data 对象字段说明 `Data` 对象包含了任务的最终状态和结果。 |**字段** |**类型** |**示例** |**描述** | |---|---|---|---| |Code |String |"Success" |任务执行结果的状态码。|\ | | | ||\ | | | |* `Success` 表示成功。|\ | | | |* `Failed` 表示失败。 | |Message |String |"AIMediaKit Task Success" |任务执行结果的描述信息。 | |TaskId |String |"amk_tool_..." |任务的唯一标识。 | |Result |Object |{...} 或 null |**任务成功时**返回的结果数据对象，失败时为 null。详见 [Result 对象](/docs/6448/2288701#56a4fd0e)。 | |CallbackArgs |String |"{\"user_id\":\"abc\"}" |自定义回调参数。如果您在提交任务时设置了 `callback_args` 参数，其内容将在此字段中原样返回。如果提交时未设置，则回调中不包含此字段。 | ### Result 对象当任务成功时，`Data.Result` 对象的具体结构因任务类型而异。 ##### 视频拼接 / 视频裁剪 / 视频叠加音频 / 图片转视频 / 画质增强这些任务的产物为视频，`Result` 对象结构如下： |**参数** |**类型** |**示例** |**描述** | |---|---|---|---| |video_url |String |`"https://.../output.mp4"` |输出视频的 URL。有效期为 48 小时。 | |duration |Number |`240.578` |输出视频的时长（单位：秒）。 | |resolution |String |`"540p"` |输出视频的分辨率。 | ##### 音频拼接 / 音频裁剪 / 从视频中提取音频这些任务的产物为音频，`Result` 对象结构如下： |**参数** |**类型** |**示例** |**描述** | |---|---|---|---| |audio_url |String |`"https://.../output.m4a"` |输出音频的 URL。有效期为 48 小时。 | |duration |Number |`180.25` |输出音频的时长（单位：秒）。 | ### 回调示例以“音视频合成”任务为例： ```JSON { "RequestId": "20260325204413EB38CD20C7D66989462D", "Version": "1.0", "EventType": "AIMediaKitTaskComplete", "EventTime": "2026-03-25T12:44:34Z", "Data": { "Code": "Success", "Message": "AIMediaKit Task Success", "TaskId": "amk_tool_mux_audio_video_14***24", "Result": { "duration": 240.578, "resolution": "540p", "video_url": "https://example.volcengine.com/output?auth_key=..." } }, "TaskId": "amk_tool_mux_audio_video_14***24" } ```

智能处理