Skip to main content
Glama

maestro_create_video

Generate a complete video or iterate on a prior one from a natural-language brief, returning a task ID to monitor progress and retrieve the final output URL.

Instructions

Create a complete video or iterate on a prior Maestro video.

One task delivers one video in one language. Successful jobs cost 0.7 Credits per actual
delivered second, never above the requested duration, with no scenario or language surcharge.
Failed jobs and task polling are free.

The call returns immediately with a task_id. Use maestro_get_task to monitor progress and obtain
the completed video's output_url, captions_url, cover_url, duration, and QC score.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>"
    },
    "name": "maestro_create_video"
  }
}

Input Schema

NameRequiredDescriptionDefault
langsNoExactly one output language code per task, such as zh-cn, en, ja, or pt-br.
styleNoVisual style preset. Named presets: cinematic, glass, luxury, swiss, modern, editorial, warm, vibrant, neon, mono, pastel, bold, industrial, futuristic, retro. Free text is also accepted as a soft visual hint. Use 'auto' or omit to let the server decide.
voiceNoNarration voice preset or a 32-character hexadecimal voice reference ID. Use 'auto' or omit to let the server decide.
actionNogenerate creates a new video. remix, edit, and extend iterate on a previous Maestro task and require ref_task_id.generate
aspectNoOutput aspect ratio: 9:16, 16:9, or 1:1. Omit to use the server default (9:16) on a new video, or to inherit the source task's ratio when iterating.
promptYesNatural-language production brief: topic, audience, scenes, tone, and desired outcome. Maestro plans the script, assets, voiceover, edit, captions, and render.
durationNoTarget video duration in seconds, from 5 to 300. Omit to use the server default (30) on a new video, or to inherit the source task's duration when iterating.
scenarioNoProduction workflow: auto, narrated, captions, avatar, or drama. Captions requires a source video in file_urls. Avatar normally needs a portrait in file_urls. Omit to let the server decide.
file_urlsNoReference image, video, or audio URLs for Maestro to use.
ref_task_idNoPrevious Maestro task ID for remix, edit, or extend.
callback_urlNoOptional webhook URL called when the task succeeds or fails.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.7
    • changedInput schema / properties / style / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "auto",
      -      "cinematic",
      -      "glass",
      -      "luxury",
      -      "swiss",
      -      "modern",
      -      "editorial",
      -      "warm",
      -      "vibrant",
      -      "neon",
      -      "mono",
      -      "pastel",
      -      "bold",
      -      "industrial",
      -      "futuristic",
      -      "retro"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "auto",
      +      "cinematic",
      +      "glass",
      +      "luxury",
      +      "swiss",
      +      "modern",
      +      "editorial",
      +      "warm",
      +      "vibrant",
      +      "neon",
      +      "mono",
      +      "pastel",
      +      "bold",
      +      "industrial",
      +      "futuristic",
      +      "retro"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / style / description
      Previous value: -"Visual style preset. Named presets: cinematic, glass, luxury, swiss, modern, editorial, warm, vibrant, neon, mono, pastel, bold, industrial, futuristic, retro. Use 'auto' or omit to let the server decide."New value: +"Visual style preset. Named presets: cinematic, glass, luxury, swiss, modern, editorial, warm, vibrant, neon, mono, pastel, bold, industrial, futuristic, retro. Free text is also accepted as a soft visual hint. Use 'auto' or omit to let the server decide."
    • changedInput schema / properties / voice / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "auto",
      -      "warm-female",
      -      "bright-female",
      -      "anchor-female",
      -      "clean-female",
      -      "calm-male",
      -      "deep-male",
      -      "documentary-male",
      -      "energetic-male",
      -      "storyteller-male"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "auto",
      +      "warm-female",
      +      "bright-female",
      +      "anchor-female",
      +      "clean-female",
      +      "calm-male",
      +      "deep-male",
      +      "documentary-male",
      +      "energetic-male",
      +      "storyteller-male"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "pattern": "^[0-9a-fA-F]{32}$",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / voice / description
      Previous value: -"Narration voice preset. Use 'auto' or omit to let the server decide."New value: +"Narration voice preset or a 32-character hexadecimal voice reference ID. Use 'auto' or omit to let the server decide."
  2. Changed2 schema fields changedv0.1.6
    • changedInput schema / properties / langs / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "type": "string"
      -    },
      -    "maxItems": 4,
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "type": "string"
      +    },
      +    "maxItems": 1,
      +    "minItems": 1,
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / langs / description
      Previous value: -"Output language codes, such as zh-cn, en, ja, or pt-br. Each language produces a localized video variant."New value: +"Exactly one output language code per task, such as zh-cn, en, ja, or pt-br."
  3. Changed2 schema fields changedv0.1.3
    • changedInput schema / properties / file_urls / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "type": "string"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "type": "string"
      +    },
      +    "maxItems": 20,
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedInput schema / properties / quality
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "enum": [
      -        "lite",
      -        "standard",
      -        "pro"
      -      ],
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "description": "Production tier: lite, standard, or pro. Omit to use the server default (standard) on a new video, or to inherit the source task's tier when iterating.",
      -  "title": "Quality"
      -}
  4. Changed1 schema field changedv0.1.2
    • removedInput schema / properties / task_id
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "format": "uuid",
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "description": "Optional client-generated UUID. Reusing it is rejected; omit it to let the server generate a task ID.",
      -  "title": "Task Id"
      -}
  5. Changed12 schema fields changedv0.1.1
    • changedInput schema / properties / duration / anyOf
      Previous value: -[
      -  {
      -    "maximum": 600,
      -    "minimum": 1,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maximum": 300,
      +    "minimum": 5,
      +    "type": "integer"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / duration / description
      Previous value: -"Target video duration in seconds, from 1 to 600. Omit to use the server default (30) on a new video, or to inherit the source task's duration when iterating."New value: +"Target video duration in seconds, from 5 to 300. Omit to use the server default (30) on a new video, or to inherit the source task's duration when iterating."
    • changedInput schema / properties / langs / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "type": "string"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "type": "string"
      +    },
      +    "maxItems": 4,
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / quality / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "draft",
      -      "standard",
      -      "premium"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "lite",
      +      "standard",
      +      "pro"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / quality / description
      Previous value: -"Production tier: draft, standard, or premium. Omit to use the server default (standard) on a new video, or to inherit the source task's tier when iterating."New value: +"Production tier: lite, standard, or pro. Omit to use the server default (standard) on a new video, or to inherit the source task's tier when iterating."
    • changedInput schema / properties / scenario / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "auto",
      -      "narrated",
      -      "drama",
      -      "avatar",
      -      "motion",
      -      "slideshow"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "auto",
      +      "narrated",
      +      "captions",
      +      "avatar",
      +      "drama"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / scenario / description
      Previous value: -"Production workflow: auto, narrated, drama, avatar, motion, or slideshow. Avatar normally needs a portrait in file_urls. Omit to let the server decide."New value: +"Production workflow: auto, narrated, captions, avatar, or drama. Captions requires a source video in file_urls. Avatar normally needs a portrait in file_urls. Omit to let the server decide."
    • changedInput schema / properties / style / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "auto",
      -      "cinematic",
      -      "glass",
      -      "luxury",
      -      "swiss",
      -      "modern",
      -      "editorial",
      -      "warm",
      -      "vibrant",
      -      "neon",
      -      "mono",
      -      "pastel",
      -      "bold",
      -      "industrial",
      -      "futuristic",
      -      "retro"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "auto",
      +      "cinematic",
      +      "glass",
      +      "luxury",
      +      "swiss",
      +      "modern",
      +      "editorial",
      +      "warm",
      +      "vibrant",
      +      "neon",
      +      "mono",
      +      "pastel",
      +      "bold",
      +      "industrial",
      +      "futuristic",
      +      "retro"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / style / description
      Previous value: -"Visual style preset or freeform style hint. Named presets: cinematic, glass, luxury, swiss, modern, editorial, warm, vibrant, neon, mono, pastel, bold, industrial, futuristic, retro. Use 'auto' or omit to let the server decide."New value: +"Visual style preset. Named presets: cinematic, glass, luxury, swiss, modern, editorial, warm, vibrant, neon, mono, pastel, bold, industrial, futuristic, retro. Use 'auto' or omit to let the server decide."
    • addedInput schema / properties / task_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "format": "uuid",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Optional client-generated UUID. Reusing it is rejected; omit it to let the server generate a task ID.",
      +  "title": "Task Id"
      +}
    • changedInput schema / properties / voice / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "auto",
      -      "warm-female",
      -      "bright-female",
      -      "anchor-female",
      -      "clean-female",
      -      "calm-male",
      -      "deep-male",
      -      "documentary-male",
      -      "energetic-male",
      -      "storyteller-male"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "auto",
      +      "warm-female",
      +      "bright-female",
      +      "anchor-female",
      +      "clean-female",
      +      "calm-male",
      +      "deep-male",
      +      "documentary-male",
      +      "energetic-male",
      +      "storyteller-male"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / voice / description
      Previous value: -"Narration voice preset, auto, or a 32-hex-character Fish reference ID. Omit to let the server decide."New value: +"Narration voice preset. Use 'auto' or omit to let the server decide."
  6. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does so well: it discloses asynchronous behavior (returns immediately with task_id), the cost model (0.7 credits per delivered second, capped at requested duration, no surcharge, failures and polling free), and where to retrieve results. These are exactly the non-obvious behavioral facts an agent needs before invoking a paid async job.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded paragraphs: purpose first, billing and language constraints second, async workflow third. Every sentence conveys information not already in the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, asynchronous, paid tool, the description covers the full lifecycle: submission, immediate return, polling via the sibling tool, and the fields available on completion. An output schema exists, so the brief enumeration of returned URLs is a bonus rather than a necessary substitute.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds value by tying duration to billing ('never above the requested duration') and reinforcing that langs is single-valued per task. It does not add syntax or format detail beyond the schema, which caps it at 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Create a complete video') and immediately covers the iteration case ('iterate on a prior Maestro video'). It is clearly distinguishable from the sibling read tools maestro_get_task and maestro_list_tasks, which are referenced later for monitoring.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to maestro_get_task for monitoring and explains that remix/edit/extend require ref_task_id, plus the constraint that one task equals one video in one language. It lacks an explicit when-not-to-use statement or guidance on choosing between the listed actions beyond the schema, so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.