Maestro Task Query API Integration Guide

The main function of the Maestro Task Query API is to query the execution status and final result of a task through the task ID returned by the Maestro Video Generation API (POST /maestro/videos). This document will provide a detailed introduction to the integration guide for the Maestro Task Query API. Since video generation is an asynchronous task, after submission, you need to use this API to poll for progress and completed videos. Polling is free and does not consume credits. POST https://api.acedata.cloud/maestro/tasks

Application Process

To use the Maestro Task Query API, first go to the Ace Data Cloud Console to obtain your API Token and keep it for later use.

If you have not yet logged in or registered, you will be automatically redirected to the login page to register and log in, and will automatically return to the current page after completion. One API Token can call all platform services; there is no need to apply separately for each service. Your first application will include free credits for a free trial; when credits are insufficient, you can top up your general balance in the console.

📘 Full documentation: Maestro Task Query API →

Query a Single Task

For how to create a video task, please refer to the Maestro Video Generation API documentation. We use one of the task IDs it returns as an example: f57e99c4f60f4373a15517742ce2357d, to demonstrate how to query its status and result.

Set Request Headers and Request Body

Request Headers include:

accept: Specifies that JSON-formatted response results are accepted; fill in application/json here.
authorization: The key for calling the API, which can be directly selected from the dropdown after application.
content-type: The format of the request body; fill in application/json here.

Request Body includes:

Field	Type	Required	Description
`id`	string	Required when querying a single task	The `task_id` returned by `POST /maestro/videos`
`action`	string	No	`retrieve` (default, query a single task); fixed as `retrieve_batch` when querying the history list

Code Examples

The corresponding CURL code is as follows:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'

The corresponding Python code is as follows:

import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Response Example

After the request succeeds, the API will return the status and result of the video task. The following is an example response when the task is completed (each language corresponds to one variant):

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

The returned result fields are described as follows:

id: The ID of this video task, used to uniquely identify this video generation task.
status: The task status, with possible values of pending → planning → producing → succeeded (or failed). Whether the task has been completed is determined by this top-level status.
elapsed: Time elapsed for the task (seconds).
progress: The top-level progress object. percent (0–100) will be set to 100 upon task success; stage and message reflect the latest progress event from the AI director (therefore, after success, stage may still be the final execution stage such as producing) and can be directly used to display a progress bar.
request: The request body when initiating the task.
response: The task response information.
- success: Whether the task succeeded.
- data.variants: Each language corresponds to one completed video object, including lang, aspect, title, output_url (completed video download URL), and more.
- data.project: The entire project output, including tarball_url (project package) and outputs (all completed video links).
- data.progress: An array of progress events appended by stage (append-only log), which can be used to display detailed real-time progress.
created_at: Task creation time, Unix timestamp (seconds).
started_at: Task start execution time, Unix timestamp (seconds). It is null when the task has not started.
finished_at: Task completion time, Unix timestamp (seconds). It is null when the task has not been completed.

Query History List

Pass action: retrieve_batch to retrieve the most recent tasks of the currently logged-in executor (in reverse chronological order by creation time), which can be used for the “My Videos” list page. The history list is isolated by login identity. Request Body includes:

Field	Type	Required	Description
`action`	string	Yes	Fixed as `retrieve_batch`
`limit`	int	No	Number of results to return, default 20; valid range is 1–100
`created_at_max`	int	No	Only return tasks strictly earlier than this Unix timestamp (excluding the boundary value, for pagination)
`created_at_min`	int	No	Only return tasks strictly later than this Unix timestamp (excluding the boundary value)

Code Example

The corresponding CURL code is as follows:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'

Response Example

After the request succeeds, the API will return the current user’s historical task list:

{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

The returned result fields are described as follows:

count: The total number of tasks visible to the currently logged-in executor, unaffected by time conditions or limit.
items: An array of tasks filtered by time conditions and limit, sorted in descending order by creation time; the format of each element is consistent with the return result of “Query a Single Task”.

Polling Recommendations

Since video production takes a relatively long time, status will go through pending → planning → producing → succeeded (or failed). It is recommended to poll every 5–10 seconds until status changes to succeeded or failed. You can use the top-level progress.percent to display a real-time progress bar. Polling this API is free and does not consume credits.

Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and message. For example:

401 invalid_token: Unauthorized, invalid or missing authorization token.
404 not_found: Task not found, the given task_id does not exist.
429 too_many_requests: Too many requests, you have exceeded the rate limit.
500 api_error: Internal server error, something went wrong on the server.

Error Response Example

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Through this document, you have learned how to use the Maestro task query API to query the status and result of a single task, as well as retrieve the current user’s historical task list. We hope this document helps you better integrate and use this API. If you have any questions, please feel free to contact our technical support team.

Maestro Video Generation API Integration Guide: Automatically produce a subtitle-enabled finished video using a natural language prompt. After submission, task_id is returned, and then use this API to poll for results.

Getting Started

Core Concepts

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Coding

More guides

Maestro Task Query API Integration Guide

Application Process

Query a Single Task

Set Request Headers and Request Body

Code Examples

Response Example

Query History List

Code Example

Response Example

Polling Recommendations

Error Handling

Error Response Example

Conclusion

​Application Process

​Query a Single Task

​Set Request Headers and Request Body

​Code Examples

​Response Example

​Query History List

​Code Example

​Response Example

​Polling Recommendations

​Error Handling

​Error Response Example

​Conclusion

​Related APIs

Application Process

Query a Single Task

Set Request Headers and Request Body

Code Examples

Response Example

Query History List

Code Example

Response Example

Polling Recommendations

Error Handling

Error Response Example

Conclusion

Related APIs