How to Track Wan Video Tasks with the Ace Data Cloud Task API

Video generation is rarely a single request-and-response workflow. A production app needs to know when a render is still running, when the final CDN URL is ready, and how to inspect or clean up task history without losing the generated asset.

This guide walks through the Wan task query API on Ace Data Cloud. The goal is small but important: build a reliable task-status layer around generated videos, using only the fields and actions documented for the endpoint.

What you can do

The Wan task endpoint is POST https://api.acedata.cloud/wan/tasks. It supports three task-history operations:

• Retrieve a single task with {"action":"retrieve","id":"TASK_ID"}.
• Retrieve multiple tasks in one request with {"action":"retrieve_batch","ids":["TASK_ID_1","TASK_ID_2"]}.
• Delete a task record with {"action":"delete","id":"TASK_ID"}.

For completed tasks, the final video URL is available at response.data.video_url. The returned response.usage includes technical metadata such as resolution, input and output video seconds, frame rate, and aspect ratio. The returned response.cost represents the settlement for the generated task.

How it works

The endpoint is intentionally action-based. Instead of creating separate URLs for read, batch read, and delete, you send a JSON body with an action value and the relevant task identifier fields.

That shape is useful when you are building a dashboard, webhook fallback, or internal job monitor. Your generation flow can store task IDs, and a later process can call /wan/tasks to reconcile the current state. If a task is still in progress, the response may not include finished_at or the final response object yet. Your UI should treat that as “not ready” rather than as a failed render.

Retrieve one task

Single-task retrieval is the core operation. Use it when a user opens a video detail page, when a worker is polling for completion, or when support needs to inspect one job.

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

In a completed task, look for response.data.video_url. The documentation describes this as a permanent CDN address, so your application can store it as the durable playback URL after completion. At the same time, capture response.usage if you need operational analytics around resolution, video duration, frame rate, or aspect ratio.

Batch query tasks for a dashboard

Most real applications do not show one render at a time. A creator dashboard might list the last twenty jobs, or an operations page might check several pending IDs together. For that case, use retrieve_batch with an ids array.

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

The documented response shape is { "items": [...], "count": 2 }. Code against that shape directly: iterate over items, display the current state of each task, and only show a playable video when the individual item has the final response data.

A practical pattern is to keep your own database row for each generated video:

• task_id: the Wan task ID returned by your generation step.
• video_url: empty until response.data.video_url appears.
• usage: copied from response.usage after completion.
• cost: copied from response.cost after completion.

That keeps the polling logic simple and lets the frontend render a clean list: pending rows for tasks without finished_at, completed rows for tasks with final response data.

Delete history without deleting the CDN video

The delete action is for task history records. According to the documentation, deleting a task record does not delete already generated CDN videos.

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

That distinction matters. If your application has already saved response.data.video_url, deleting task history should not be treated as media deletion. Use this operation for cleanup policies around task records, not as a replacement for your own media lifecycle rules.

A small Python polling helper

Here is a minimal helper you can adapt for a backend worker. It retrieves one task and returns the final CDN URL only when the task response is present.

import requests

API_KEY = "YOUR_API_KEY"
TASK_ID = "TASK_ID"

r = 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,
)
r.raise_for_status()
task = r.json()

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

Keep the retry cadence in your own worker conservative, and avoid treating a missing final response as an error. The task may simply still be rendering.

Where this fits in a builder workflow

If you are building with video generation, the task endpoint is the glue between generation and playback. Store task IDs, reconcile them with retrieve or retrieve_batch, save response.data.video_url once available, and clean task history only when your product no longer needs the record.

For the exact request bodies and response notes, see the Wan Task Query API documentation.