A Practical Guide to Querying Wan Video Tasks with Ace Data Cloud

When you build around asynchronous video generation, the hard part is often not the generation request itself; it is keeping reliable track of each job until the finished video is actually available.

The Wan task query API in Ace Data Cloud is designed for that practical middle layer. A video generation workflow can submit work, store the returned task ID, and later use a single task endpoint to retrieve status, inspect the final response, batch-check multiple jobs, or remove task history records after your own system has persisted what it needs.

What you can do

The documented endpoint is POST https://api.acedata.cloud/wan/tasks. It supports three task-management actions:

• retrieve: query one Wan video task by id.
• retrieve_batch: query multiple tasks by passing an ids array.
• delete: delete a task history record by id.

That small surface area is useful in production because it maps directly to common backend concerns: poll one job for a user-facing status page, reconcile many jobs in a worker, or clean up records that no longer need to be displayed in your dashboard.

How it works

The endpoint is called with a JSON body. For a single task lookup, the required fields shown in the documentation are action and id. The request uses bearer authentication and Content-Type: application/json.

Here is the canonical shape:

curl -X POST 'https://api.acedata.cloud/wan/tasks'   -H 'Authorization: Bearer YOUR_API_KEY'   -H 'Content-Type: application/json'   -d '{"action":"retrieve","id":"TASK_ID"}'

When the task is completed, the documented final video location is available at response.data.video_url. The same completed response also includes response.usage, which reports generation metadata such as resolution, input and output video seconds, frame rate, and aspect ratio. The documented response.cost field contains the settlement for the generated task.

Polling one task without overcomplicating it

A minimal backend implementation usually needs only two states: “not finished yet” and “has a final response.” The documentation notes that when tasks are still in progress, there may not yet be a finished_at timestamp or a final response. That means your polling loop should not assume the video URL exists on every read.

In practice, store the task ID in your own database when you create the Wan video task. Then run a worker that calls retrieve at a reasonable interval. If finished_at is missing, keep the job pending. If finished_at is present and response.data.video_url exists, persist the CDN URL in your application and move the job into a completed state.

Batch-checking tasks for queues and dashboards

If your product generates many videos at once, a one-request-per-task polling loop can become noisy. The documented batch query action lets you send an array of task IDs:

{"action":"retrieve_batch","ids":["TASK_ID_1","TASK_ID_2"]}

The response shape documented for batch retrieval is:

{ "items": [...], "count": 2 }

This is a good fit for a dashboard refresh, a nightly reconciliation job, or a queue worker that wants to update several pending rows in one pass. The same completion rule still applies: an in-progress task may not yet include finished_at or its final response, so your code should treat missing completion fields as normal rather than exceptional.

Deleting task history records safely

The delete action is intentionally about task history, not media deletion. The documented body is:

{"action":"delete","id":"TASK_ID"}

The important operational detail is that deletion only affects the task history record. It does not delete an already generated CDN video. That distinction matters if your app has already copied response.data.video_url into its own database or user-facing project record. You can clean up task history without assuming the generated video disappears.

A small Python polling example

The following example keeps the logic deliberately plain. It retrieves one task, checks whether completion metadata is present, and then reads the documented CDN URL only after the final response exists.

import requests

API_KEY = "YOUR_API_KEY"
TASK_ID = "TASK_ID"

resp = requests.post(
    "https://api.acedata.cloud/wan/tasks",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"action": "retrieve", "id": TASK_ID},
    timeout=30,
)
resp.raise_for_status()
task = resp.json()

if not task.get("finished_at") or not task.get("response"):
    print("Task is still in progress")
else:
    video_url = task["response"]["data"]["video_url"]
    usage = task["response"].get("usage")
    cost = task["response"].get("cost")
    print("Video:", video_url)
    print("Usage:", usage)
    print("Cost:", cost)

Where this fits in a real builder workflow

The cleanest pattern is to separate generation from retrieval. Your frontend or API server can create a Wan generation task, but a background worker should own task retrieval. That worker can use retrieve for user-triggered status checks, retrieve_batch for queue maintenance, and delete only after your application no longer needs the task history record.

For builders, the main value is predictable state management: task ID in, completion fields out, permanent CDN video URL once available, plus usage and cost metadata for internal reporting. You can read the source documentation here: Wan Task Query API integration guide.