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 Maestro Task Query API integration guide. Since video generation is an asynchronous task, you need to use this API to poll for progress and the finished video after submission. Polling is free and does not consume credits.

POST https://api2.yujuntc.fun/maestro/tasks

Application Process

To use the Maestro Task Query API, first obtain your API Token from the 语钧AI Console 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 you 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 includes 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 its returned task IDs as an example: f57e99c4f60f4373a15517742ce2357d, to demonstrate how to query its status and result.

Set Request Headers and Request Body

Request Headers include:

  • accept: Specifies receiving response results in JSON format; enter 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; enter application/json here.

Request Body includes:

Field Type Required when 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 Example

The corresponding CURL code is as follows:

curl -X POST 'https://api2.yujuntc.fun/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://api2.yujuntc.fun/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. An example response when the task is complete is as follows (the variants array contains one finished video):

{
  "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"
    ],
    "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"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.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 possible 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 default to 100 after the task succeeds; stage and message reflect the AI director's most recent progress event (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: Contains one finished video object in the selected language, including lang, aspect, title, output_url (finished video download URL), and more.
    • data.project: The entire project output, including tarball_url (project package) and outputs (finished 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.
  • finished_at: Task completion time, Unix timestamp (seconds). It is null when the task has not completed.

Query History List

Pass action: retrieve_batch to obtain 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 returned, default is 20; valid range is 1–100
created_at_max int No Return only tasks strictly earlier than this Unix timestamp (excluding the boundary value, for pagination)
created_at_min int No Return only tasks strictly later than this Unix timestamp (excluding the boundary value)

Code Example

The corresponding CURL code is as follows:

curl -X POST 'https://api2.yujuntc.fun/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"
        ],
        "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 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 result returned by "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 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 can help you better integrate with and use this API. If you have any questions, please feel free to contact our technical support team.