Maestro Video Generation API Integration Instructions

Maestro is a native Agent 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 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; 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 on 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 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 main language; for each additional language, the same footage is reused, only voiceover + rendering is added, each additional +6 points.
aspect string No 9:16 (default) / 16:9 / 1:1 (aspect ratio hint, AI may adjust based on prompt).
duration int No Target duration (seconds, 1–600, i.e., up to 10 minutes), default is 30. Billing is based on the actual final video length, the longer it is, the more expensive (see billing below).
quality string No Production tier (multiplier affecting duration pricing): draft (quick preview rough cut, about 0.5× of standard tier) / standard (default, balanced, 1×) / premium (more refined, more outstanding, takes longer, about 2× of standard tier).
scenario string No Video type routing hint (only a hint, the AI director still decides the final structure): auto (default) / narrated (multiple scenes with real photos + narration + data cards) / drama (characters + dialogue short play) / avatar (digital person / voiceover, must use file_urls to transmit the portrait) / motion (abstract dynamic subtitles / data / logo effects) / slideshow (presentation / roadshow deck).
style string No Visual style preset: 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 (language-independent, 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": "Explain what a vector database is in 20 seconds, suitable for a zero-based audience, ending with a memorable point.",
  "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": "Explain what a vector database is in 20 seconds, suitable for a zero-based audience, and end with a memorable point",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

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

Clicking run, you can find that you will immediately get a result, as follows:

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

The fields in the returned result are described as follows:

  • success: Whether the task was successfully submitted.
  • task_id: The ID of this video generation task, which will be used to poll the 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. Next, you need to use task_id to poll the results, see the "Get Results" section for details.

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 certain type, you can explicitly pass it. For example, to create a vertical short drama, you can specify the following content:

  • scenario: Video type, set to drama (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, three acts of reversal, ending warmly",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'

Common combinations:

  • Short drama: scenario: "drama" (characters + dialogue).
  • Digital person / voiceover: scenario: "avatar", and use file_urls to provide a portrait.
  • Dynamic subtitles / data animation: scenario: "motion"; demonstration / roadshow: scenario: "slideshow".
  • style is a preset visual style (such as 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 (such as warm-female / deep-male), which is language-independent and cross-language applicable.

The returned 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 main language, and for each additional language, it 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 result (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 differential modifications based on the original project (such as "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 a more impactful one, and darken the overall color scheme"
}'
  • remix: Reinterpret the original video structure (retain the theme, adjust the presentation).
  • edit: Refine specific parts (such as changing titles, changing voiceovers, color grading).
  • extend: Extend content based on the original video.

The returned result is also immediately 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 immediately returns task_id after submission, and you need to use it to poll 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

Tasks are billed based on the actual final product, and failed tasks are not charged. Billing is based on the actual delivered product duration and the actual number of languages produced— for example, if you request 600 seconds but the final product is 50 seconds, you will only be billed for approximately 50 seconds; if a certain language does not produce a final output, the +6 surcharge for that language will not be charged. Submitting a task itself is not billed separately (results can be polled for free via /maestro/tasks).

The points for a single final product are roughly estimated by the following formula:

Points ≈ 0.85 × final product duration in seconds × quality multiplier × scenario multiplier + 6 × max(number of languages - 1, 0)
  • Quality multiplier: draft 0.5× / standard 1× (default) / premium 2×.
  • Scenario multiplier: drama 1.35× / avatar 1.15× / others 1×.

For standard quality, non-short drama / digital person, and single language, the points for different final product durations are approximately:

Duration of the video clip Standard points
30s 25.5
60s 51
120s (2 minutes) 102
300s (5 minutes) 255
600s (10 minutes, upper limit) 510
Each additional language (more than 1 langs, for each additional one) +6
Polling /maestro/tasks 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.

Example of Error Response

{
  "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 video 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.