Maestro Video Generation API Integration Instructions

Maestro is an Agent Native video production interface: you describe the desired video in a natural language prompt (optionally attaching reference images/videos/audios with file_urls), and a headless “AI director” will automatically complete the topic selection, script writing, scene generation, voiceover, music, synthesis, and rendering, ultimately producing a subtitled final product and uploading it to the CDN. This article will provide detailed instructions for integrating the Maestro video generation API, 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 of charge). To continue iterating on an existing video, you can use action: remix / edit / extend along 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 for future use.

If you are not logged in or registered, you will be automatically redirected to the login page to invite 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, without needing to apply separately for each service. The first application will grant a free quota for you to experience it for free; when the quota is insufficient, you can recharge the general balance in the console.

📘 Complete Documentation: Maestro Video Generation API →

Basic Usage

POST https://api.acedata.cloud/maestro/videos The most basic usage requires only passing in a natural language prompt, and the AI director will automatically decide the script, scenes, voiceover, and editing. Here we will first understand the request headers and request body that need to be set. Request Headers include:

accept: the format of the response result you want to receive, here it is filled in as application/json, which means JSON format.
authorization: the key to call the API, which can be directly selected after application.
content-type: the format of the request body, here it is filled in as application/json.

Request Body mainly includes:

prompt: a natural language description of the video to be made (theme, what to showcase, style, audience).
langs: an array of output languages, such as ["zh-cn", "en"], default is ["zh-cn"].
aspect: aspect ratio, 9:16 (default) / 16:9 / 1:1.
duration: target duration (seconds), default is 30.

The complete fields of the request body are shown in the table below:

Field	Type	Required	Description
`prompt`	string	Yes	A natural language description of the video to be made (theme, what to showcase, style, audience). The script, scenes, voiceover, and editing are all determined by AI
`action`	string	No	`generate` (default, generate a new video) / `remix` / `edit` / `extend` (iterate on an existing video, must be used with `ref_task_id`)
`ref_task_id`	string	No	Required when `action` is remix / edit / extend: the historical task `task_id` as a starting point
`file_urls`	string[]	No	Reference media (image/video/audio URLs), such as product images, logos, or material clips to add subtitles
`langs`	string[]	No	Output languages, such as `["zh-cn", "en"]`, default is `["zh-cn"]`. The first is the primary language; for each additional language, reuse the scenes, only add voiceover + rendering, each additional +6 points
`aspect`	string	No	`9:16` (default) / `16:9` / `1:1`, uniformly output 1080p/30fps
`duration`	int	No	Target duration (seconds), default is 30, supports 5–300 seconds. Billing is based on the actual final video length but will not exceed the requested duration
`scenario`	string	No	Video type: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` requires the source video, `avatar` requires a portrait
`style`	string	No	Visual style presets: `auto` (default) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, also accepts free text as a soft prompt. Orthogonal to `scenario`, does not change routing
`voice`	string	No	Voiceover tone (independent of language, cross-language universal): `auto` (default) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`

Below is a specific example to demonstrate. Suppose we want to generate a bilingual (Chinese and English), vertical, 20-second science popularization short video, the corresponding CURL code is as follows:

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'

The corresponding Python code is as follows:

import requests

url = "https://api.acedata.cloud/maestro/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Clicking run, you will find that an immediate result is obtained, as follows:

{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}

The description of the fields in the returned result is as follows:

success: Whether the task was successfully submitted.
task_id: The ID of the video generation task, which will be used to poll for results via the Maestro Task Query API.
trace_id: The tracking ID of this request, which can be provided to technical support for troubleshooting.

Since video production takes a long time, the interface will immediately return task_id and will not wait for the video rendering to complete. You will need to use task_id to poll for results, as detailed in the “Get Results” section.

Specify Video Type and Style (scenario / style)

If scenario is not provided, AI will automatically determine it (equivalent to auto); if you want to pin the video to a specific type, you should specify it explicitly. For example, to create a vertical short drama, you can specify the following content:

scenario: Video type, set to drama (a short drama with characters + dialogue).
style: Visual style, set to cinematic (film quality).

The sample CURL code is as follows:

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Two co-renting roommates fall out and reconcile over a cat, with three acts of twists and a warm ending",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'

Common combinations:

Narrated short video: scenario: "narrated", supported by Lite / Standard / Pro.
Automatic subtitles: scenario: "captions", requires file_urls to pass the source video, supported by Lite / Standard / Pro.
Digital human / voiceover: scenario: "avatar", requires file_urls to pass a portrait, supported by Standard / Pro.
Short drama: scenario: "drama" (characters + dialogue), supported only by Pro.
style is a preset visual style (e.g., modern / neon / luxury), which does not change the type but only affects the visual experience.
voice is used to specify the tone of the narration (e.g., warm-female / deep-male), independent of language and applicable across languages.

The return result is consistent with “Basic Usage,” also immediately returning task_id.

Multilingual Output

By passing multiple languages in langs, you can produce multilingual versions at once. The first is the primary language, and each additional language will reuse the same set of visuals, only adding voiceover + rendering, so each additional language only adds +6 points. Example:

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "Introduce our intelligent customer service product, highlighting 3 core selling points",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'

After the task is completed, each language will correspond to a variant in the results (see Maestro Task Query API).

Iterate on Existing Videos (remix / edit / extend)

By passing action and the previous task’s ref_task_id, you can make incremental modifications based on the original project (e.g., “change the title of Act 2,” “change the voiceover,” “darken the overall tone”). Small changes are quick, while large changes will be redone:

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "Change the opening title to something more impactful, and darken the overall color scheme"
}'

remix: Reinterpret the original video structure (retain the theme, adjust the presentation).
edit: Refine specific parts (e.g., change title, change voiceover, adjust color).
extend: Expand content based on the original video.

The return result will also immediately return a new task_id, which you can use to poll for the final product after iteration.

Get Results

Since video production takes a long time, this interface will immediately return task_id after submission, and you need to use it to poll for results via the Maestro Task Query API:

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"
}'

When the task is completed, it will return the final product information (each language corresponds to a variant). The status will go through pending → planning → producing → succeeded (or failed), polling is free and does not consume points. For the complete response format and historical list query, please refer to the Maestro Task Query API Integration Guide.

Billing

Billing is based on the actual completed product after the task is finished, and failed tasks are not charged. Billing is based on the actual delivered product duration and the number of languages, and the billed duration will not exceed the requested duration. If a certain language does not produce a final output, the +6 surcharge for that language will not be charged. Submitting the task itself is not charged separately, and /maestro/tasks polling is free. The points for a single completed product are calculated as follows:

Points = Completed product duration in seconds × 0.60 × Scenario multiplier + 6 × max(Number of languages - 1, 0)

Maestro uniformly charges 0.60 points/actual completed seconds, supporting 5–300 seconds, up to 4 languages, and 1080p / 30fps output; all actions and scenarios are available. Scenario multipliers: drama 1.35× / avatar 1.15× / others 1×.

Example	Points
Lite 30 seconds	6
Standard 30 seconds	18
Standard 60 seconds	36
Standard 120 seconds	72
Pro 30 seconds	36
Pro 300 seconds	360
Each additional actual delivered language	+6
`/maestro/tasks` polling	Free

Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and message. For example:

400 invalid_request: Bad request, possibly due to a missing prompt or 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

{
  "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 video generation API: with just a natural language prompt, you can automatically complete scripts, materials, voiceovers, music, editing, subtitles, and rendering, and it supports specifying video types, styles, tones, multilingual output, and iterating on existing videos. We hope this document helps you better connect and use the API. If you have any questions, please feel free to contact our technical support team.

Maestro Task Query API Integration Instructions: Use the task_id returned by POST /maestro/videos to query the task status and results, or to pull the history of task lists (polling is free).

Getting Started

Core Concepts

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Coding

More guides

Maestro Video Generation API Integration Instructions

Application Process

Basic Usage

Specify Video Type and Style (scenario / style)

Multilingual Output

Iterate on Existing Videos (remix / edit / extend)

Get Results

Billing

Error Handling

Error Response Example

Conclusion

​Application Process

​Basic Usage

​Specify Video Type and Style (scenario / style)

​Multilingual Output

​Iterate on Existing Videos (remix / edit / extend)

​Get Results

​Billing

​Error Handling

​Error Response Example

​Conclusion

​Related Interfaces

Application Process

Basic Usage

Specify Video Type and Style (scenario / style)

Multilingual Output

Iterate on Existing Videos (remix / edit / extend)

Get Results

Billing

Error Handling

Error Response Example

Conclusion

Related Interfaces