Step 3: Create and Query a Task

Gitruck Cloud image, audio, and video APIs follow an asynchronous task model. You create a task first, then poll the task endpoint for status and results.

This section focuses on the two groups of "how long do I still need to wait?" fields:

The create-task API returns snapshot values captured at creation time
The query-task API returns dynamic remaining durations computed at query time

All duration fields use seconds and keep 2 decimal places.

Create a Task

This example uses image watermark removal:

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"
  }'

Success Example

{
  "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
  }
}

Duration Fields in the Create Response

Field	Meaning	Dynamic?
`estimated_duration`	Estimated processing time after the task actually starts running, excluding queue wait time	No
`estimated_queue_wait_duration`	Snapshot of the estimated queue wait time at task creation	No
`estimated_total_duration`	Total estimated time at creation, equal to `estimated_queue_wait_duration + estimated_duration`	No
`remaining_total_duration`	Current remaining total wait time; in the create response it is equal to `estimated_total_duration`	Equal to the total estimate at creation

You can think of them like this:

estimated_duration: once the task starts running, how long the processing is expected to take
estimated_queue_wait_duration: before processing starts, how long the task is expected to wait in queue
estimated_total_duration: how long the user is expected to wait in total from now

💡 Tip: estimated_queue_wait_duration is a snapshot taken at creation time. It is preserved for audit and later analysis, instead of being overwritten on each poll.

Query the Task

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

Result Example

The following example shows a task that has already entered processing. In this phase, remaining_total_duration is usually the best value to show to end users:

{
  "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": "Image Watermark Removal",
    "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 Fields in the Query Response

Field	Meaning	UI suggestion
`estimated_total_duration_snapshot`	Total estimated time captured when the task was created	Use it for "initial estimate" or analysis
`remaining_queue_wait_duration`	Current remaining queue wait time	Good for "still waiting in queue"
`remaining_processing_duration`	Current remaining processing time	Good for "processing, about X seconds left"
`remaining_total_duration`	Current remaining total wait time	Best default field to show users
`actual_duration`	Real processing time from the first `processing` state until a terminal state, excluding queue time	Useful after completion for reporting or analysis

Why These Fields Are Split Into Snapshot Values and Dynamic Values

Snapshot fields preserve the prediction baseline recorded when the task was created
Dynamic fields tell the user how much time is left right now
The query API should return decreasing remaining time, instead of the unchanged values captured at creation

How to Interpret Remaining Time by Status

Status	Behavior
`created` / `queued`	`remaining_queue_wait_duration` keeps decreasing, while `remaining_processing_duration` usually stays equal to `estimated_duration`
`processing`	`remaining_queue_wait_duration = 0`, and `remaining_processing_duration` keeps decreasing
`completed` / `failed` / `cancelled`	All `remaining_*` fields become `0`

Frontend Display Suggestions

When a task is newly created or still queued, show remaining_total_duration first
If you want to explain whether the task is still queued or already running, also show remaining_queue_wait_duration and remaining_processing_duration
Once the task is completed, replace the waiting hint with download or output information

Status Reference

Status	Description
`created`	Task just created
`queued`	Task entered the queue
`processing`	Task is running
`completed`	Task completed
`failed`	Task failed
`cancelled`	Task cancelled

💡 Tip: Poll every 2 to 5 seconds. Once you get output_result.file_id, you can call the file detail API to resolve the download URL.