`GET https://amk.cn-beijing.volces.com/api/v1/tasks/{task_id}` 本接口用于查询指定 `task_id` 的异步任务状态和最终结果。在提交异步任务后，您可以间隔一定时间轮询此接口来获取任务的最新动态。 :::tip 在生产环境中，您也可配置[事件回调](/docs/6448/2288701)。配置后，AI MediaKit 会在任务完成时主动将结果推送到您的服务器，从而避免不必要的轮询。 ::: ## 接口特性 * **统一查询**：支持查询 AI MediaKit 服务下所有类型的异步任务（如视频拼接、画质增强等）。 * **结果时效**：任务成功后的结果数据（如下载链接）默认在系统内保留 2 天，请及时下载保存资源。 * **自动续期**：当任务结果的剩余有效期不足 2 小时，调用本接口会自动延长其有效期，避免链接过早失效。 ## 请求参数 ### Path 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`task_id` |String |是 |`amk-tool-mux-audio-video-14***24` |任务的唯一标识。在提交异步任务时，从响应体中获取。 | ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](/docs/6448/2300661)获取 API Key。 | ## 请求示例 ```Bash curl -X GET "https://amk.cn-beijing.volces.com/api/v1/tasks/amk-tool-mux-audio-video-14***24" \ -H "Authorization: Bearer {your_amk_api_key}" ``` ## 响应参数接口的响应体为一个 JSON 对象，包含了任务的详细信息。 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |标识本次 API 请求是否被成功处理。|\ | | ||\ | | |* `true`：服务端成功处理了查询请求。|\ | | |* `false`：请求失败，具体原因请查看 `error` 字段。|\ | | ||\ | | |:::tip|\ | | |此字段仅代表查询操作本身是否成功，不代表任务的执行状态。|\ | | ||\ | | |:::| |`task_id` |String |所查询任务的唯一标识。 | |`task_type` |String |任务类型。例如 `mux-audio-video`（视频加音频）、`enhance-video`（画质增强）等。 | |`status` |String |任务当前的状态。枚举值：|\ | | ||\ | | |* `running`：任务正在处理中。|\ | | |* `completed`：任务已成功完成。|\ | | |* `failed`：任务处理失败。 | |`result` |Object |**任务成功时**返回的结果对象。仅当 status 为 completed 时出现。其内容结构请参见下文[Result 对象](/docs/6448/2278532#z1bF4vdwsd)。 | |`error` |Object |**任务失败时**返回的错误详情对象，或在任务成功时为 `null`。其内容结构请参见下文 [Error 对象](/docs/6448/2278532#qKBD8INQb7)。 | |`expires_at` |String |任务结果的过期时间戳（Unix Time，单位：秒）。仅当任务成功且有结果时返回。 | |`created_at` |String |任务创建时间戳（Unix Time，单位：秒）。 | |`finished_at` |String |任务完成（成功或失败）的时间戳（Unix Time，单位：秒）。仅当 `status` 为 `completed` 或 `failed` 时出现。 | |`request_id` |String |本次 API 请求的唯一标识符，可用于问题排查。 | ### Result 对象当 `status` 为 `completed` 时，响应会包含 `result` 对象。其具体结构因 `task_type` 而异。以下为不同任务类型对应的 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` |输出音频的时长（单位：秒）。 | ### Error 对象当 `success` 为 `false` 或 `status` 为 `failed` 时，会返回 `error` 对象，包含错误详情。 |参数 |类型 |描述 | |---|---|---| |`code` |String |错误码。详见[错误码](/docs/6448/2300662)。 | |`message` |String |错误描述信息，用于展示或记录日志。 | |`param` |String |(可选) 指示导致错误的具体参数名。 | |`type` |String |错误类型，如 `TaskError` 表示任务执行出错，`ApiError` 表示 API 调用出错。 | ## 响应示例 ### 示例 1：任务正在运行 ```JSON { "success": true, "task_id": "amk-tool-mux-audio-video-14***24", "task_type": "concat-video", "status": "running", "created_at": 1700484518, "request_id": "202603252052226AE61BF072A5A596F761" } ``` ### 示例 2：任务成功完成（以音视频叠加为例） ```JSON { "success": true, "task_id": "amk-tool-mux-audio-video-14***24", "task_type": "mux-audio-video", "status": "completed", "result": { "video_url": "https://storage.example.com/outputs/027e3f5e-fa22-4a3f-a05e-9c8e79c45562.mp4?auth_key=...", "resolution": "540p", "duration": 240.578 }, "expires_at": "1774615474", "created_at": "1774442654", "finished_at": "1774442675", "request_id": "202603252052226AE61BF072A5A596F761" } ``` ### 示例 3：任务执行失败 ```JSON { "success": true, "task_id": "amk-tool-mux-audio-video-14***24", "task_type": "concat-video", "status": "failed", "error": { "code": "DownloadFailed", "message": "Failed to download file from the provided URL: https://example.com/nonexistent.mp4. Please check if the URL is correct and publicly accessible.", "param": "inputs[1].url", "type": "TaskError" }, "created_at": 1700484518, "finished_at": 1700484522, "request_id": "202603252052226AE61BF072A5A596F761" } ```

智能处理