Maestro Video

Maestro End-to-End Video Production

Use Maestro when the user wants a finished video, not only a generated clip. A headless AI director turns one natural-language brief into a script, visual assets, voiceover, music, edit, captions, quality checks, and rendered video variants.

Setup: See authentication for token setup.

Choose Maestro When

• The user wants an article, idea, product brief, or campaign turned into a complete video.
• The workflow needs scripting, visuals, narration, captions, and editing handled together.
• The user supplies product images, a logo, portrait, source footage, or reference audio.
• One visual production must be rendered in multiple languages.
• A completed Maestro video needs to be remixed, edited, or extended.

Use a model-specific video API such as Seedance, Kling, or Veo when the user only needs a short generated shot and wants direct model controls. Maestro may use multiple media services internally and is optimized for the finished production.

Quick Start

curl -X POST https://api.acedata.cloud/maestro/videos \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 30-second beginner-friendly video explaining vector databases. End with one memorable takeaway.",
    "aspect": "16:9",
    "duration": 30,
    "scenario": "narrated",
    "langs": ["en"]
  }'

The successful creation response is HTTP 201 and contains a task_id. Maestro is asynchronous, so query the task until it reaches succeeded or failed:

curl -X POST https://api.acedata.cloud/maestro/tasks \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "<task_id>", "action": "retrieve"}'

Do not invent output URLs or report completion while the task is still running.

Core Workflow

1. Translate the user's goal into a concrete production brief.
2. Call POST /maestro/videos and preserve the returned task_id and trace_id.
3. Poll POST /maestro/tasks at a reasonable interval.
4. Continue through nonterminal states; stop only at succeeded or failed.
5. On success, return every item in response.data.variants, including its language and output_url.
6. If requested, iterate by creating a new task with action, ref_task_id, and a change-focused prompt.

Polling and history queries are free; the video task is settled after production based on delivered output. Avoid submitting duplicate creation requests while an existing task is still running.

Creation Parameters

Production contract

Every request uses the complete production capability: all actions and scenarios, 5–300 seconds, up to 4 languages, and 1080p/30fps output. The base price is 0.60 Credits per delivered second. Avatar uses a 1.15× multiplier, drama uses 1.35×, and each additional delivered language adds 6 Credits. Failed tasks and polling are free.

Scenarios

• auto: let the director choose from the brief.
• narrated: multi-scene explainer, documentary, brand, history, or product video with voiceover.
• captions: add kinetic captions to a source video supplied in file_urls.
• avatar: talking-head or digital-human video; provide a portrait in file_urls.
• drama: acted short drama with characters and dialogue (Pro only).

Styles

Named presets include cinematic, glass, luxury, swiss, modern, editorial, warm, vibrant, neon, mono, pastel, bold, industrial, futuristic, and retro. The API also accepts a freeform style hint.

Voices

Available presets include:

• Female: warm-female, bright-female, anchor-female, clean-female
• Male: calm-male, deep-male, documentary-male, energetic-male, storyteller-male
• Automatic: auto

Voice controls timbre rather than language. The same preset speaks the language selected in langs.

Reference Media

Pass public URLs in file_urls:

{
  "prompt": "Create a product launch video that clearly shows the camera body and logo. Use the supplied audio as the tone reference.",
  "file_urls": [
    "https://example.com/product.jpg",
    "https://example.com/logo.png",
    "https://example.com/reference.mp3"
  ],
  "scenario": "narrated",
  "style": "editorial",
  "aspect": "16:9"
}

Reference URLs must be reachable by the service. Do not pass local file paths. Upload local assets first, then use their public URLs.

Multilingual Variants

Use one request to reuse the production across languages:

{
  "prompt": "A concise product walkthrough for first-time customers",
  "langs": ["en", "de", "ja"],
  "voice": "warm-female",
  "duration": 45
}

The first language is primary. A successful task normally returns one item per delivered language in response.data.variants. Do not assume every requested language succeeded; inspect the actual variants.

Iterate on a Previous Video

All iteration actions require ref_task_id.

Remix

Use remix for a new creative interpretation that keeps the previous task as context:

{
  "action": "remix",
  "ref_task_id": "previous-task-id",
  "prompt": "Rework this as a faster social cut with a stronger opening hook and neon styling.",
  "aspect": "9:16"
}

Edit

Use edit for targeted revisions:

{
  "action": "edit",
  "ref_task_id": "previous-task-id",
  "prompt": "Keep the structure and visuals. Replace the final call to action and use a calmer narrator."
}

Extend

Use extend to continue or lengthen the production:

{
  "action": "extend",
  "ref_task_id": "previous-task-id",
  "prompt": "Add a 15-second customer example before the conclusion.",
  "duration": 60
}

Iteration creates a new task. Continue polling the new task_id; do not overwrite or confuse it with the source task.

Task Response

A task response exposes top-level progress for user feedback:

{
  "id": "task-id",
  "status": "producing",
  "progress": {
    "percent": 52,
    "stage": "visuals",
    "message": "Generating scene assets",
    "activity": "Creating scene 4"
  },
  "response": null
}

On success, inspect the delivered variants:

{
  "status": "succeeded",
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "en",
          "output_url": "https://cdn.example/video.mp4",
          "captions_url": "https://cdn.example/captions.vtt",
          "cover_url": "https://cdn.example/cover.jpg",
          "duration": 31.2,
          "qc_score": 0.96
        }
      ]
    }
  }
}

Treat the fields above as a shape guide. Return fields that are actually present; never fabricate missing captions, covers, durations, or QC scores.

Task Retrieval

Retrieve a task by its required id; the only documented action is retrieve:

curl -X POST https://api.acedata.cloud/maestro/tasks \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "TASK_ID", "action": "retrieve"}'

Prompting Guidance

A useful brief answers:

• What is the subject and desired outcome?
• Who is the audience?
• What facts, products, people, or scenes must appear?
• What should the viewer feel or do afterward?
• Which platform determines aspect ratio and pacing?
• Are there exact brand, compliance, or wording constraints?

Prefer a concrete production brief over a list of low-level model instructions. Maestro is responsible for choosing and orchestrating media tools.

Gotchas

• This API is asynchronous. Always preserve and poll the returned task_id.
• Terminal states are succeeded and failed; other status names may evolve as the production pipeline changes.
• remix, edit, and extend fail without ref_task_id.
• file_urls must be public URLs, not local paths.
• avatar usually needs a usable portrait reference.
• Requested duration is a target; report the actual delivered duration from the result.
• Multilingual requests may return fewer variants than requested if one output fails.
• Do not resubmit the same brief merely because a long-running poll has not finished.
• Do not expose the API token in logs, output, source files, or examples.

MCP: pip install mcp-maestro | Hosted: https://maestro.mcp.acedata.cloud/mcp | See all MCP servers