Maestro Video Generation API

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, composition, and rendering, producing a final video with subtitles and uploading it to the CDN.

This is an asynchronous task interface: after submission, it immediately returns a task_id, and you can then poll POST /maestro/tasks for results (polling is free), or provide a callback_url for a callback upon completion. To iterate on an existing video, use action: remix / edit / extend along with ref_task_id.

¶ Authentication

All requests must include the API Token in the Header:

authorization: Bearer {token}

You can obtain a Token by registering and creating an application at https://platform.acedata.cloud.

¶ Submit Task

POST https://api.acedata.cloud/maestro/videos

curl -X POST https://api.acedata.cloud/maestro/videos \
  -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
  }'

Response:

{ "success": true, "task_id": "f57e99c4f60f4373a15517742ce2357d", "trace_id": "…" }

¶ Request Parameters

Field	Type	Required	Description
`prompt`	string	Yes	Describe the video to be made in natural language (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, requires `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 segments to add subtitles.
`langs`	string[]	No	Output languages, e.g., `["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` (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. Charged by duration, longer is more expensive (see pricing 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). Affects output speed, detail, and price.
`scenario`	string	No	Video type routing hint (only a hint, the AI director still decides the final structure): `auto` (default, automatically determine) / `narrated` (multiple scenes with real photos + narration + data cards, suitable for people/brands/science/history/products) / `drama` (characters + dialogue short play) / `avatar` (digital person / voiceover, requires `file_urls` for portrait or selected digital person) / `motion` (abstract dynamic subtitles / data / logo animations) / `slideshow` (presentation / roadshow deck). Old values `general` / `explainer` / `product` / `website` / `changelog` / `captions` are still compatible (mapped to `auto`), `slides` maps to `slideshow`.
`style`	string	No	Visual style hint (e.g., `cinematic` / `minimal` / `neon` / `corporate` / `hand-drawn`), affecting layout, color scheme, motion effects, scene processing, and rhythm; orthogonal to `scenario`, does not change routing. Default is `auto` (no style hint).
`callback_url`	string	No	Callback this address when the task enters a terminal state (success/failure).

¶ Specify Video Type and Style (scenario / style)

If scenario is not provided, AI will automatically determine (equivalent to auto); if you want to pin the video to a certain type, explicitly provide it. For example, to create a vertical short play:

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

Short play: scenario: "drama" (characters + dialogue).
Digital person / voiceover: scenario: "avatar", and provide a portrait using file_urls.
Dynamic subtitles / data animations: scenario: "motion"; presentation / roadshow: scenario: "slideshow".
style is free text visual hint (e.g., minimal / neon / corporate), does not change type, only affects perception.

¶ Get Results

POST https://api.acedata.cloud/maestro/tasks

curl -X POST https://api.acedata.cloud/maestro/tasks \
  -H "authorization: Bearer {token}" \
  -H "content-type: application/json" \
  -d '{ "id": "f57e99c4f60f4373a15517742ce2357d" }'

When the task is completed, it returns (each language corresponds to a variant):

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "status": "succeeded",
  "elapsed": 312,
  "request": { "prompt": "…", "langs": ["zh-cn", "en"], "aspect": "9:16", "duration": 20 },
  "response": {
    "success": true,
    "data": {
      "variants": [
        { "lang": "zh-cn", "aspect": "9:16", "kind": "video", "title": "What is a vector database", "output_url": "https://…/zh.mp4" },
        { "lang": "en", "aspect": "9:16", "kind": "video", "title": "What is a vector database", "output_url": "https://…/en.mp4" }
      ],
      "project": { "tarball_url": "https://…/project.tar.gz", "outputs": ["https://…/zh.mp4", "https://…/en.mp4"] },
      "progress": [ { "stage": "planning", "message": "writing the script", "pct": 20, "t": 1750000000 } ],
      "stage": "succeeded"
    }
  }
}

status values: pending → planning → producing → succeeded (or failed). response.data.progress provides stage progress, which can be used to display a real-time progress bar. Polling is free and does not consume points.

¶ Iterating on Existing Videos (remix / edit / extend)

Pass action and the previous task's ref_task_id to make incremental modifications based on the original project (e.g., "change the title of scene 2", "change the voiceover", "darken the overall tone"), small changes are quick, large changes will be redone:

curl -X POST https://api.acedata.cloud/maestro/videos \
  -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 line, darken the overall color scheme"
  }'

¶ Billing

Points are pre-deducted based on duration length upon submission, formula:

Points = (60 + 1.7 × duration seconds) × quality multiplier + 6 × max(language count - 1, 0)

Quality multiplier: draft 0.5× / standard 1× (default) / premium 2×. Common durations (standard tier, single language):

Duration	Standard Tier Points
30s	111
60s	162
120s (2 minutes)	264
300s (5 minutes)	570
600s (10 minutes, limit)	1080
Each additional language (`langs` exceeds 1)	+6
`/maestro/tasks` polling	Free