Skip to main content
Glama

Cast a music video

cast_music_video

The director proposes who else is in it: up to 3 new people, each drawn as a character sheet only after a yes Optional, after the idea and before the lookbook and the shot list (nobody appears on screen without a character sheet). Free (a limited number an hour), a few seconds: returns a casting whose people (at most 3, never more than the model's room in a shot beside the performer and the people already given) each have a role, a first name, what they do (does), a description their sheet is drawn from, and about how many shots they are in. With cast_mode exact, nobody on screen or no room, it proposes nobody (status ready, people []), without a director call. Show each person with price.per_person (price.credits for all); the user may drop anyone, edit a description, or put a kit character in that role instead; then draw_music_video_cast after their yes, or order the video with casting_id to draw them inside the order. Same brief as plan_music_video. Needs an active plan (402 plan_required without one; get_account: plan.active).

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": {
      "song_id": "<song_id>"
    },
    "name": "cast_music_video"
  }
}

Input Schema

NameRequiredDescriptionDefault
castNoThe performer in it, kept from their character: what they wear, outfit_kit (a kit outfit's @handle, without the @, worn in every shot they are in); left out, the director picks. Only when the performer is on screen
trimNoOnly this section of the song (15 seconds to 10 minutes); omitted, the whole song (15 seconds to 10 minutes long). Best: a part from get_song_analysis (parts[]: its start and end never cut a word)
modelNoThe music video model: one-take (default; MiniMax H3 Max), seedance-2-0, seedance-2-0-fast, seedance-2-0-mini or seedance-2-5. get_options lists the models offered to you with the categories, styles, formats, takes and length each makes, and guide: what each is best for, its strengths, weaknesses and public benchmark scores. When the person hasn't named a model, suggest the kind's recommended_model (get_options music_video.categories) with its best_for line and the price difference between models from quotes, and let them choose anyone-take
styleNoOptional visual style (get_options: music_video.styles); omitted, the director picks one from the cover
takesNoHow the shots meet: "cuts" (default: shots meet with a cut between the song's lines, like an edit) or "continuous" (the director may carry a shot on into the next through a picture drawn of the moment they meet, priced per picture; the quote before a plan counts every join, the plan's quote only the ones it draws)cuts
peopleNo
scenesNoWhere it is set besides the places the direction mentions from the kit: {"mode":"invent"} (default: the director imagines the others) or {"mode":"stock"} (it finds a real stock photo of each place it writes, empty of people, and the artist is put into it), up to the model's kit.places in all
lipsyncNo"auto" (default: the director has the artist sing the important lines on camera) or "never" (nobody sings on camera; the song plays over every shot). A kind sung on camera (lyric-led) refuses "never"; an instrumental song never lip-syncsauto
look_idNoA music video Look (list_music_video_looks: one made public, or the workspace's own) the video follows: its treatment leads the director and its places and props join the kit. Send its category, style, takes and lipsync too (or your own)
song_idYesThe song; its artist performs the video and needs their character (list_characters; start_character makes one), unless performer names another character
categoryNoperformance (default), intercut, cinematic, story or surrealperformance
kit_onlyNoOnly what the kit's pictures show: no place, prop, person or lighting change beyond them (every shot in one of the kit's places, lit as in its picture; only the props and the people the brief names). Omitted: on when the brief mentions a kit piece by @handle (an outfit, a place or a prop), off otherwise; send false to let the director add to the kit
cast_modeNoWho else may be on screen besides the performer and people: "director" (default when left out: the director may cast up to 3 more, each drawn as a character sheet only after the user says yes: cast_music_video) or "exact" (only who was picked; the song's other people are carried by the scene, an empty chair or a coat left out, never shown). Nobody appears on screen without a character sheet; with nobody cast, crowds and dancers are faceless. A cast-story video with "exact" needs people
directionNoOptional notes for the director (a place, an era, a story idea, a mood). Mention kit pieces by @handle (list_kit): "@nina-kazora in the @blue-set on the @rooftop, the @chrome-mic in hand"; a mentioned piece is used exactly as it is and the director designs the rest. Mention characters by @handle (list_characters) to put them in the shots beside the performer (those in the song's artist's kit and those other artists shared, list_characters with for_artist_id; the song's artist's own too when another character performs; in a story with a cast, they are the cast): "@mia-torres dances behind her in the last chorus". An unknown handle, or another artist's piece they haven't shared, answers 400. Pin a change to a moment with a sentence that says on "<words sung>" (on every "…" for each time they are sung) or at m:ss (the song's time), for example: On "Drop it" cut to @rooftop-club. / @grandma appears on "She said yes". / At 1:05 the lights go out. A shot starts exactly there (the plan has one more shot when the usual cut runs over it), set in the first kit place the sentence names, with the characters it names appearing in it (and not in the shot before); shots[].cue shows it. Words the section doesn't sing, or two moments under 2 seconds apart, answer 400
on_screenNoWho is on screen: artist (the song's artist, from their character; in a Creator workspace the character performer names), cast (people the director casts and describes; the artist needn't appear) or none (places, light and objects). Omitted: the kind's (cast-story a cast, mood and places no one, else the artist). Only what the model makes: get_options lists on_screen per model (cast and none are offered once a model is tested with them). Without the artist no character is needed and there are no outfits; continuous takes join on the cast and the place
performerNoOnly in a Creator workspace (its projects have no character of their own): who performs (sings to camera lip-synced, or plays), a character in the song's project's kit or one another project shared (list_characters with for_artist_id: its id, kit_…). Anywhere else the song's artist performs, from their character: leave it out. Only when someone performs (on_screen artist: every kind but cast-story, mood and places).
aspect_ratioNo"9:16" (default), "16:9" or "1:1"9:16

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the bar is lower. The description adds cost and rate-limit context ('Free (a limited number an hour)'), latency ('a few seconds'), the returned casting shape, and the no-director-call outcome for cast_mode exact.

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

Conciseness2/5

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

The purpose is front-loaded, but the description is a dense, run-on block with parentheticals and semicolons that make it hard to scan. There is also redundancy around the character-sheet rule and awkward phrasing such as 'after a yes Optional', which weakens structure despite the useful content.

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 a 17-parameter tool with no output schema, the description is thorough: it explains return fields, the empty-cast outcome, pricing visibility, prerequisites, and the downstream flow. It gives an agent enough context to call the tool correctly and interpret its result.

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

Parameters3/5

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

Schema description coverage is 94%, so the input schema already carries most parameter meaning and a baseline of 3 is appropriate. The description adds useful behavior for cast_mode exact ('it proposes nobody (status ready, people [])'), but does not add much semantic detail for the other 16 parameters beyond what the schema already provides.

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?

The opening sentence names the specific action (the director proposes who else is in the video), the resource (new people / casting), and the scope (up to 3). It explicitly distinguishes this from draw_music_video_cast and from ordering with casting_id, so an agent can identify the tool without opening the schema.

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

Usage Guidelines5/5

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

It states when the tool applies (optional, after the idea and before the lookbook and shot list), what to do next (draw after the user's yes, or order with casting_id), and which sibling to use (draw_music_video_cast). It also states the prerequisite (active plan, 402 plan_required) and the cast_mode exact exception.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources