Maestro Task Query API Integration Instructions

The main function of the Maestro Task Query API is to query the execution status and final results of a task using the task ID returned by the Maestro Video Generation API (POST /maestro/videos).

This document will provide detailed instructions for integrating the Maestro Task Query API. Since video generation is an asynchronous task, after submission, this interface needs to be polled to obtain progress and the final product, 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 obtain your API Token from the Ace Data Cloud Console for future use.

If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page.

One API Token can call all services on the platform, no need to apply separately for each service. The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the console.

📘 Complete documentation: Maestro Task Query API →

Query a Single Task

For information on how to create a video task, please refer to the document Maestro Video Generation API. We will use a task ID returned by it as an example: f57e99c4f60f4373a15517742ce2357d, demonstrating how to query its status and results.

Set Request Headers and Request Body

Request Headers include:

  • accept: Specifies that the response result should be in JSON format, set to application/json.
  • authorization: The key to call the API, which can be selected directly after application.
  • content-type: The format of the request body, set to application/json.

Request Body includes:

Field Type Required Description
id string Yes The task_id returned by POST /maestro/videos
action string No retrieve (default, query a single task) / retrieve_batch (query historical task list)

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 '{
  "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 a successful request, the API will return the status and results of the video task. An example of the return when the task is completed is as follows (each language corresponds to a 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": "Explain what a vector database is in 20 seconds, suitable for a zero-based audience, and end with a memorable point",
    "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://…/zh.mp4"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://…/en.mp4"
        }
      ],
      "project": {
        "tarball_url": "https://…/project.tar.gz",
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

The field descriptions of the returned result are as follows:

  • id: The ID of this video task, used to uniquely identify this video generation task.
  • status: The task status, with values pending → planning → producing → succeeded (or failed). Whether the task is completed is determined by this top-level status.
  • elapsed: The time spent on the task (in seconds).
  • progress: The top-level progress object, percent (0–100) will be capped at 100 after the task is successful; stage and message reflect the most recent progress event from the AI director (thus after success, stage may still be the last executed stage such as producing), which can be directly used to display a progress bar.
  • request: The request body when initiating the task.
  • response: The return information of the task.
    • success: Whether the task was successful.
    • data.variants: Each language corresponds to a final product object, containing lang, aspect, title, output_url (download link for the final product), etc.
    • data.project: The entire project output, containing tarball_url (project package) and outputs (all final product 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: The task creation time, Unix timestamp (in seconds).
  • started_at: The time the task started execution, Unix timestamp (in seconds). It is null when the task has not yet started.
  • finished_at: The time the task was completed, Unix timestamp (in seconds). It is null when the task is not completed.

Query Historical List

By passing action: retrieve_batch, you can obtain the recent tasks of the current user (in reverse order of creation time), which can be used for the "My Videos" list page.

Request Body includes:

Field Type Required Description
action string Yes Fixed as retrieve_batch
limit int No Number of returns, default is 20
created_at_max int No Only return tasks earlier than this Unix timestamp (for pagination)
created_at_min int No Only return tasks later than this Unix timestamp

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 a successful request, the API will return the current user's history 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://…/zh.mp4"
            }
          ]
        }
      }
    }
  ]
}

The fields in the returned result are described as follows:

  • count: The total number of tasks for the current user.
  • items: An array of tasks, where each element's format is consistent with the return result of "query a single task".

Polling Suggestions

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

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 check the status and results of a single task, as well as to pull the current user's history 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.