Logo

第三步：创建并查询任务

同合云的图片、音频、视频处理能力都采用异步任务模型。你需要先创建任务，再通过查询接口轮询任务状态。

创建任务

下面以图片去水印为例：

curl -X POST https://api.ai-mcn.tv:10000/task/image_purify \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246"
  }'

成功响应示例

{
    "code": 200,
    "msg": "success",
    "data": {
        "task_id": "537489015178247",
        "task_type": "image_purify",
        "status": "queued",
        "input_params": {
            "file_id": "537489015178246"
        },
        "created_at": "2026-04-05T08:00:01Z",
        "estimated_duration": 8.5,
        "estimated_queue_wait_duration": 1.2,
        "estimated_total_duration": 9.7,
        "remaining_total_duration": 9.7
    }
}

创建接口中的等待时长字段说明

字段名含义是否动态变化
estimated_duration任务真正开始执行后的预估处理耗时，不包含排队时间否
estimated_queue_wait_duration创建任务那一刻的排队预计等待时间快照否
estimated_total_duration创建时总预估时长，等于 estimated_queue_wait_duration + estimated_duration否
remaining_total_duration当前剩余总等待时长；在创建响应里它与 estimated_total_duration 相等创建时等于总预估

你可以把它们理解为：

  • estimated_duration：真正开始跑之后，大概还要处理多久
  • estimated_queue_wait_duration：在开始跑之前，大概还要排多久队
  • estimated_total_duration：用户从现在开始，理论上一共要等多久

💡 提示：estimated_queue_wait_duration 是创建瞬间的快照值，便于审计和后续分析，不会随着轮询不断覆盖更新。

查询任务

curl -X GET https://api.ai-mcn.tv:10000/task/image_purify/537489015178247 \
  -H "Authorization: YOUR_API_KEY"

查询结果示例

下面示例展示的是任务已经进入 processing 后的返回结果，此时前端最适合展示 remaining_total_duration：

{
    "code": 200,
    "msg": "success",
    "data": {
        "id": "537489015178247",
        "status": "processing",
        "progress": 42,
        "input_params": {
            "file_id": "537489015178246"
        },
        "output_result": null,
        "estimated_duration": 8.5,
        "estimated_queue_wait_duration": 1.2,
        "estimated_total_duration_snapshot": 9.7,
        "remaining_queue_wait_duration": 0,
        "remaining_processing_duration": 5.5,
        "remaining_total_duration": 5.5,
        "actual_duration": null,
        "unit_duration_snapshot_sec": 8.5,
        "estimate_unit_count": 1,
        "task_type_key": "image_purify",
        "task_type_name": "图片去水印",
        "consume_info": {
            "consume_type": "quota"
        },
        "create_time": "2026-04-05T08:00:01Z",
        "process_start_time": "2026-04-05T08:00:04Z",
        "finish_time": null,
        "update_time": "2026-04-05T08:00:07Z"
    }
}

查询接口中的 ETA 字段说明

  • 创建任务接口返回的是创建时的耗时快照
  • 查询任务接口返回的是当前时刻的动态剩余时长

所有耗时字段统一使用 秒 作为单位，并保留 2 位小数。

字段名含义展示建议
estimated_total_duration_snapshot创建任务时的总预估快照用于展示“最初预估”或做统计分析
remaining_queue_wait_duration当前剩余排队时间适合展示“预计排队中”
remaining_processing_duration当前剩余处理时间适合展示“处理中，预计还需 X 秒”
remaining_total_duration当前剩余总等待时长最适合直接展示给用户
actual_duration真实处理耗时，从首次进入 processing 到终态为止，不包含排队任务结束后用于复盘或统计

这些字段为什么分成“快照”和“动态值”

  • 快照字段用于保留任务创建当时的预测基线，便于后续分析预测是否准确
  • 动态字段用于用户轮询时展示“现在还要等多久”
  • 查询接口返回的剩余时间会随着时间推移而减小，而不会永远停留在创建的那一刻

不同状态下，剩余时长如何理解

状态字段表现
created / queuedremaining_queue_wait_duration 逐步减少，remaining_processing_duration 通常等于 estimated_duration
processingremaining_queue_wait_duration = 0，remaining_processing_duration 继续下降
completed / failed / cancelled所有 remaining_* 字段都会变为 0

前端展示建议

  • 任务刚创建或排队中时，优先展示 remaining_total_duration
  • 如果想让用户知道“是在排队还是已经开始处理”，可以同时展示 remaining_queue_wait_duration 和 remaining_processing_duration
  • 任务完成后，隐藏等待提示，改为展示结果下载或产物信息

状态说明

状态值说明
created任务刚创建
queued已进入队列
processing正在处理
completed已完成
failed处理失败
cancelled已取消

💡 提示：建议根据ETA字段设计轮询策略。拿到 output_result.file_id 后，可继续调用文件详情接口查询下载地址。

下一步