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 introduce the integration guide for the Maestro Task Query API in detail. 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://xapi.zhishuyun.com/maestro/tasks

Application Process

To use the Maestro Task Query API, first go to the 知数云 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 and invited to register and log in. After completion, you will automatically return to the current page.

One API Token can call all platform services, with no need to apply separately for each service. The first application includes free credits for free trial; when credits are insufficient, you can recharge 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 responses in JSON format 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 when querying a single task Description
id string Required when querying a single task The task_id returned by POST /maestro/videos
action string No retrieve (default, queries 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://xapi.zhishuyun.com/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://xapi.zhishuyun.com/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://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.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: Task status, with values 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 defaulted to 100 after the task succeeds; stage and message reflect the most recent progress event from the AI director (therefore, after success, stage may still be the last 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 response information of the task.
    • success: Whether the task succeeded.
    • data.variants: Each language corresponds to one completed video object, containing lang, aspect, title, output_url (completed video download URL), and more.
    • data.project: The entire project output, containing 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 execution start time, Unix timestamp (seconds). It is null when the task has not started yet.
  • finished_at: Task completion time, Unix timestamp (seconds). It is null when the task has not been completed.

Query History List

Pass in action: retrieve_batch to obtain the most recent tasks of the current logged-in executor (in reverse order of 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 returned items, default is 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://xapi.zhishuyun.com/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 historical task list of the current user:

{
  "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://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

The fields in the returned result 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 returned 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 once 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 is encountered, 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 historical task list of the current user. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team.