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 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 YuJun 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 inviting 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 free credits for a trial experience; when credits are 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 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 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`. Lite outputs 720p/24fps, Standard and Pro output 1080p/30fps
`duration`	int	No	Target duration (seconds), default is 30. Lite is 5–30 seconds, Standard is 5–120 seconds, Pro is 5–300 seconds. Charged based on the actual final video duration, but will not exceed the requested duration
`quality`	string	No	Production level: `lite` (quick short video, 0.20 points/second) / `standard` (default, balanced production, 0.60 points/second) / `pro` (high-end production, 1.20 points/second)
`scenario`	string	No	Video type: Lite supports `auto` / `narrated` / `captions`; Standard adds `avatar`; Pro adds `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 applicable): `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-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, and end 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)

Click to run, and you will find that you 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 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 immediately returns task_id and does not wait for the video rendering to complete. Next, you need to use task_id to poll for 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 (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 reversal 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 visual style preset (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), independent of language and applicable across languages.

The returned result is the same as "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 voiceovers + 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" or "change the voiceover" or "darken the overall tone"). Small changes are quick, while large changes will require a redo:

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: Make fine-tuning to specific parts (such as changing titles, voiceovers, color grading).
extend: Expand content based on the original video.

The returned result will also immediately return a new task_id, which can be used 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 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 final product after the task is completed, 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 ultimately does not produce a result, the +6 surcharge for that language will not be charged. Submitting a task itself is not charged separately, and /maestro/tasks polling is free.

The points for a single final product are calculated as follows:

Points = Final product duration in seconds × SKU price per second × scenario multiplier + 6 × max(number of languages - 1, 0)

SKU	Price per Second	Maximum Duration	Output	Scenarios and Actions
`lite`	0.20 points	30 seconds	720p / 24fps	auto, narrated, captions; generate, edit
`standard`	0.60 points	120 seconds	1080p / 30fps	add avatar; add remix
`pro`	1.20 points	300 seconds	1080p / 30fps high bitrate	add drama; add extend

Scene 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
For each additional actual delivery 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 support specifying video types, styles, tones, multilingual output, and iterating on existing videos. We hope this document helps you better integrate 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 POST /maestro/videos to return the task_id to query task status and results, or pull the historical task list (polling is free).