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://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 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; enterapplication/jsonhere.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; enterapplication/jsonhere.
Code Example
The corresponding CURL code is as follows:Response Example
After the request succeeds, the API returns the status and results of the video task. An example response when the task is complete is shown below (thevariants array contains one completed video):
id: The ID of this video task, used to uniquely identify the video generation task.status: The task status. Possible values arepending → planning → producing → succeeded(orfailed). Whether the task has been completed is determined by this top-levelstatus.elapsed: The elapsed time for the task (in seconds).progress: The top-level progress object.percent(0–100) is 100 when the task succeeds;stageandmessagereflect the most recent progress event from the AI director (therefore, after success,stagemay still be the last execution stage, such asproducing). It can be used directly to display a progress bar.request: The request body used to initiate the task.response: The task response information.success: Whether the task was successful.data.variants: Contains one completed video object for the selected language, includinglang,aspect,title,output_url(the completed video download URL), and more.data.project: The complete project output, includingtarball_url(the project package) andoutputs(completed video links).data.progress: An array of progress events appended by stage (an append-only log), which can be used to display detailed real-time progress.
created_at: The task creation time, as a Unix timestamp (in seconds).started_at: The time when the task started execution, as a Unix timestamp (in seconds). This is null if the task has not started yet.finished_at: Task completion time, Unix timestamp (seconds).nullif the task is not completed.
Query History List
Passaction: 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:
Code Example
The corresponding CURL code is as follows:Response Example
After the request succeeds, the API will return the current user’s historical task list:count: The total number of tasks visible to the currently logged-in executor, unaffected by time conditions orlimit.items: An array of tasks filtered by time conditions andlimit, 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
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.Related APIs
- Maestro Video Generation API Integration Guide: Automatically produce a finished video with subtitles using a natural language prompt. After submission,
task_idis returned, and then use this API to poll for the result.

