prompt to describe the video you want (optionally attach reference images / videos / audio with file_urls), and a headless “AI director” will automatically complete topic selection, scriptwriting, visual generation, voice-over, background music, compositing, and rendering, ultimately producing a finished video with subtitles and uploading it to the CDN.
This article will introduce the integration guide for the Maestro Video Generation API in detail, helping you quickly integrate and fully utilize the capabilities of this API.
This is an asynchronous task interface: after submission, it will immediately return a task_id, and you can then poll for results through the Maestro Task Query API (POST /maestro/tasks) (polling is free and not billed). To continue iterating on an existing video, you can use action: remix / edit / extend together with ref_task_id.
Application Process
To use the Maestro Video Generation 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 Video Generation API →
Basic Usage
POST https://api.acedata.cloud/maestro/videos
For the most basic usage, you only need to provide a natural-language prompt. The AI Director will automatically determine the script, visuals, voice-over, and editing. Let’s first review the request headers and request body that need to be configured.
Request Headers include:
accept: The desired response format. Set this toapplication/json, i.e., JSON format.authorization: The API key. After applying for one, you can select it directly from the dropdown.content-type: The request body format. Set this toapplication/json.
prompt: Describe the video to create in natural language (topic, what to show, style, and audience).langs: An array of output languages. Pass only one language each time, such as["zh-cn"]. The default is["zh-cn"].aspect: Aspect ratio:9:16(default) /16:9/1:1.duration: Target duration (seconds). The default is 30.
The following example demonstrates the process. Suppose we want to generate a 20-second, vertical Chinese science explainer video. The corresponding cURL code is as follows:
success: Whether this task was submitted successfully.task_id: The ID of this video generation task. Use it to poll for results through the Maestro Task Query API.trace_id: The tracking ID for this request. If you encounter an issue, provide it to technical support for troubleshooting.
task_id and does not wait for video rendering to complete. Next, use task_id to poll for the result. See the “Retrieve Results” section for details.
Specify Video Type and Style (scenario / style)
Whenscenario is not provided, it is automatically determined by AI (equivalent to auto); if you want to pin the video to a certain type, explicitly provide it. For example, to create a vertical short drama, you can specify the following:
scenario: Video type, set todramahere (a short drama with characters + dialogue).style: Visual style, set tocinematichere (cinematic quality).
- Narrated short video:
scenario: "narrated". - Automatic subtitles:
scenario: "captions", requiring the source video to be passed throughfile_urls. - Digital human / talking-head video:
scenario: "avatar", requiring a portrait image to be passed throughfile_urls. - Short drama:
scenario: "drama"(characters + dialogue). styleis a visual style preset (such asmodern/neon/luxury), which does not change the type and only affects the visual appearance.voiceis used to specify the narration voice (such aswarm-female/deep-male), which is language-independent and works across languages.
task_id is also returned immediately.
Final Video Language
One task delivers one final video in one language only.langs can contain only one language code, such as ["zh-cn"] or ["en"]; passing multiple languages will return 400. If you need videos in different languages, please create tasks separately. Language selection does not change the per-second price.
Iterate on an Existing Video (remix / edit / extend)
Passaction and the ref_task_id of the previous task to make incremental modifications based on the original project (such as “change the title of Scene 2,” “change the voice-over,” or “make the overall tone darker”). Small changes are fast, while major changes will require regeneration:
remix: Reinterpret based on the original video structure (retain the theme while adjusting the presentation).edit: Fine-tune specific parts (such as changing titles, voice-over, or color grading).extend: Extend content based on the original video.
task_id; use it to poll and retrieve the final video after iteration.
Retrieve Results
Since video production takes a relatively long time, this API immediately returnstask_id after submission. You need to use it to poll the result via the Maestro Task Query API:
variants array). status will go through pending → planning → producing → succeeded (or failed), and polling is free and does not consume credits. For the complete response format and historical list queries, please refer to the Maestro Task Query API Integration Guide.
Billing
Billing is based on the actual duration of the delivered final video after the task succeeds; failed tasks are not charged. The billable duration is calculated in whole seconds and does not exceed the requested duration; if the final video duration cannot be read, it falls back to the requested duration. Submitting a task itself is not billed separately, and/maestro/tasks polling is free.
Error Handling
When calling the API, if an error occurs, the API returns the corresponding error code and message. For example:400 invalid_request: Bad request, possibly due to a missingpromptor invalid parameters.401 invalid_token: Unauthorized, invalid or missing authorization token.403 forbidden: Forbidden, insufficient balance or access.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 Video Generation API: with just one natural-languageprompt, you can automatically complete scriptwriting, asset selection, voice-over, background music, editing, subtitles, and final video rendering. It also supports specifying video type, style, voice, final video language, and iteration on existing videos. 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.
Related APIs
- Maestro Task Query API Integration Guide: Use the
task_idreturned byPOST /maestro/videosto query task status and results, or retrieve the historical task list (polling is free).

