> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro Video Generation API Integration Instructions

> Maestro AI Video Studio integration guide - Ace Data Cloud

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](/en/guides/maestro/maestro_tasks) (`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](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Complete Documentation: [Maestro Video Generation API →](https://platform.acedata.cloud/documents/maestro-videos)

## 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:

```bash theme={null}
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:

```python theme={null}
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:

```json theme={null}
{
  "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](/en/guides/maestro/maestro_tasks).
* `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:

```bash theme={null}
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:

```bash theme={null}
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](/en/guides/maestro/maestro_tasks)).

## 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:

```bash theme={null}
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](/en/guides/maestro/maestro_tasks):

```bash theme={null}
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](/en/guides/maestro/maestro_tasks).

## 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

```json theme={null}
{
  "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.

## Related Interfaces

* [Maestro Task Query API Integration Instructions](/en/guides/maestro/maestro_tasks): 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.