bitwize-music-studio/claude-ai-music-skills / skills/music-video
music-video
VerifiedMakes a music video for a track through Suno's Sequences - shots laid out on the song's sections, a keyframe for each, a free animatic to judge the pacing, then generated clips for the shots the user chooses - and saves the animatic and the finished video beside the album's audio. Laying out and exporting are free; keyframes and clips spend Visuals credits, priced and approved step by step. Use when the user asks for a music video, a storyboard or an animatic for a track.
Your Task
Input: $ARGUMENTS
Take one track's approved take to a music video on Suno, a stage at a time: lay the shots out, make their keyframes, export an animatic, turn the shots the user chooses into clips, and save the result.
The user decides the look, who is on screen, which take of a shot to keep, and what to spend. You price, ask and wait.
Music Video Skill
Suno's Sequences lay a music video out as a timeline of shots over a song. Each shot holds a still, its keyframe, until a generated clip replaces it, and the cut can be exported at any point. With only keyframes in it, the export is an animatic: the stills held in time with the song, to judge the pacing before paying for clips.
What it costs, in Visuals credits, a balance of its own beside song and download credits:
| Stage | Cost |
|---|---|
| Laying the shots out, changing the cut, exporting, downloading | Free (measured) |
| A keyframe | Per shot: 1 on image-1 (Fast). Suno's own default, image-4, is 50 |
| A clip | Per second: 15 on video-1 (480p), 30 on video-2 (720p). Charged by the whole second, rounded up: a 9.44-second shot is charged as 10 |
A whole song as clips costs thousands: three minutes at 480p is about 2,700. That is why the animatic comes first, and why most videos keep stills for most shots. Say so before any work, in Step 3.
Measured on a six-shot test: six keyframes cost 6 credits and a five-second clip 75, each charged when its call was made and ready in under a minute. Still unmeasured, and written from Suno's tool descriptions: characters, a shot that fails, and the rate-limit, refusal and unknown answers.
Every paid call is sent for real once. It goes out exactly as it was priced, with a key fixed beforehand, and it is sent again only where Step 6's table says so. A shot that holds a take, or is making one, is never made again unless the user asks for that and approves its price.
Background, the answers each tool gives, and what was and was not measured: ${CLAUDE_PLUGIN_ROOT}/reference/suno/mcp-api-mapping.md § Visuals.
Step 1: Plan
Expected format: <album-name> <track> [--shape 16:9|1:1|9:16]
If the album or the track is missing, show:
Usage: /music-video <album-name> <track> [--shape 16:9|1:1|9:16]
Example: /music-video sample-album 03
Call get_music_video_plan(album_slug, track_slug, shape). The shape is 16:9 unless the user names another.
| Result | Do |
|---|---|
found: false, or an error | Report it and stop |
| A blocking problem | Show its detail and stop. no_keeper: the user approves a take first |
no_master | Say the video will carry Suno's own audio, and carry on |
video_exists | Tell the user. The question whether to replace it comes in Step 9 |
Step 2: Check the Suno Server
Find sequence-create, sequence-generate, sequence-update, sequence-get, sequence-list, sequence-export, visuals-wait, visuals-download, visuals-models, audio-analysis, audio-retrieve, audio-download and account-usage on a connected MCP server, and load their definitions.
Not there → say so and stop. Either Suno's server is not connected, or this session started before Suno added the tools and needs a restart.
Call account-usage and keep the three balances. Call visuals-models and keep each model's price: credits_per_generation for an image model, credits_per_second for a video model. Both calls are free.
Then look for a Sequence this track already has, before planning anything: one that is found and missed would be paid for twice.
sequence-list(query: <sequence_title>). A page can be short, or empty, and still carry acursor: pass it back until a page has none, ten pages at most.- For each one whose title is the
sequence_title,sequence-get(id, view: "full"). It is this track's only if itssong_idissong.clip_id. Tell the user if itsaspectis not the shape asked for: the video is saved under the Sequence's shape. - Found one → ask whether to carry on with it or start another. To carry on, read each shot's
statusand follow Carrying On below. None → Step 3.
Carrying On
A Sequence keeps what was made. Never make again what a shot already holds or is making:
| A shot reads | It | Do |
|---|---|---|
gap | Has nothing | It needs a keyframe (Step 6) |
processing | Is being made, and is paid for | Wait for it: visuals-wait with its generation_id. Never start it again |
ready, media_type: image | Has its keyframe | Leave it. It can become a clip (Step 8) if the user picks it |
ready, media_type: video | Has its clip | Leave it |
failed | Lost its generation | See Step 8, item 7 |
Go to the earliest step some shot still needs, and put only the shots that need it in that step's batches. Skip Steps 3 to 5, except audio-retrieve and the lock check in Step 3, which every run needs.
Step 3: The Song, and What the Video Would Cost
-
audio-retrieve(id: <song.clip_id>). Keepmetadata.duration. -
Find out whether the song is locked:
audio-download(id: <song.clip_id>, format: "mp3")withoutconfirm.status: "ok"→ unlocked.status: "requires_credit"→ locked: keep that for Step 7, where the first download happens, and spend nothing now.rate_limited→ wait the seconds it names and call again. Any other refusal → report it and stop. -
audio-analysis(id: <song.clip_id>). Whilestatusisprocessing, call it again, six times at most; it usually takes about a minute. Keepsections,bpm,time_signature, and thetime_sof the first beat whosebar_positionis 1. The answer is long: do not repeat it to the user. If it endsunavailable, carry on with no sections. -
plan_music_video_shots(duration_s, sections, bpm, time_signature, first_downbeat_s, credits_per_second: <video-1's price>). -
Tell the user the scale before anything else. For example:
First Track (3:26) lays out as 22 shots. Keyframes for all of them: 22 Visuals credits on image-1. Every shot as a clip: 210 billed seconds, about 3,150 credits at 480p or 6,300 at 720p. You have 1,000. Three ways to go: 1. An animatic: keyframes held as stills, in time with the song. 2. Clips for a few shots you pick, stills for the rest. 3. Every shot a clip.Ask which. Nothing has been spent, and nothing is made on Suno until Step 5.
Step 4: The Look
Three things are the user's to choose, so ask unless they have said:
- The look: the style, the palette, anything that must not appear (text, faces, logos).
- Who or what is on screen. A performer, characters, or no one.
- Whether anyone sings on screen, and whether the words are burned in (
lyrics).
A performer or a place that should look the same from shot to shot needs reference images that are already on Suno, one to three each: the asset ids of images made there, or the user's saved characters from characters-list. Without them, leave characters and sets out: each shot is then drawn from its prompt alone, and faces will not match between shots. Say so if the user wants a performer.
A set holds well (measured): three shots citing one reference image showed the same objects and the same place. It also outweighs the prompt: a shot that asked for one object alone showed the several in the reference. So cite a set only in shots that should show what its images show.
Then draft the storyboard: one line a shot, saying what it shows, the framing and how the camera moves, all within the look. Show it as a table with each shot's number, start time, length and section, and change it until the user approves it. The lengths come from Step 3; to change them, plan again with another max_shot_s.
Step 5: Lay It Out (free)
get_music_video_plan(album_slug, track_slug, shape, shots: [{duration_s, notes, characters?, set?}], style, lyrics, characters, sets). A blockingrequest_invalid→ show itsdetailand stop. Keeprequest. Ifrequestis null, stop and say what is missing; never put the arguments together yourself.- Call
sequence-createwith exactly the keys ofrequestandidempotency_key: "{album_slug}/{track_slug}/music-video/create/{UTC timestamp}", the time filled in once: a retry after an error sends the same string, so it cannot make a second Sequence. Keep thesequence_id, theeditor_url, and every shot'sshot_idwith its number.
Tell the user the editor_url: they can rearrange, trim and retime the shots on suno.com at any point, and sequence-get reads what they changed.
Step 6: Keyframes (paid)
One image a shot, made from a prompt: the look, then the shot's line from the storyboard. Name the characters and the set in the prompt as the Sequence names them.
-
The model.
image-1unless the user asks for another. Always name it: left out, Suno usesimage-4at 50 credits a shot. -
Price it. This spends nothing.
sequence-generatetakes up to 8 shots a call, so split the shots into batches of 8 and write each batch down: the real call sends it unchanged. For each batch callsequence-generate(id: <sequence_id>, step: "keyframes", model, shots: [{shot_id, prompt}], dry_run: true). Each answer carriesdry_run: true, its price ascredits, and for every shot themodelit priced: check that it is the one you named. Add the batches up. If the model differs, the tool no longer listsdry_run, refuses it, or answers withoutdry_run: true, stop and tell the user. Never dropdry_runto get a call through. -
State the cost and wait. "Keyframes for 22 shots on image-1: 22 Visuals credits. You have 1,000." The balance is the dry run's
visuals_credits_remaining, which is today's, not the one read in Step 2. More than the balance → say so and stop. Do not generate until the user says go. -
Generate, once a batch. Fix each batch's key before its first attempt and write it down:
"{album_slug}/{track_slug}/music-video/keyframes/{batch number}/{UTC timestamp}", the time filled in. Then send each batch exactly as it was priced, withoutdry_runand with its key. Add nothing the price did not cover. -
Read each shot's
statusin the answer. One call can answer with several, andmoderation_limitedon any shot comes first.Status Do moderation_limitedStop the whole stage: send nothing more, not even shots still waiting. Tell the user. Do not retry startedIt is being made and is paid for. Keep its generation_idstarted, with anerrorbeside itIt started but is not in its shot yet. Wait for it like the others, then put the take in its shot with sequence-update(id, shots: [{shot_id, asset_id}]). Never make it againrate_limitedIt did not start and was not charged. Wait retry_after_seconds, then send only those shots, with the prompts they were priced with, as a batch of their own with a new key. Three rounds at most; then tell the user which shots are still waitingrefusedIt did not start. Show the reason. If the prompt named a real artist, character or person, offer one revised prompt; once the user approves it, that shot goes alone: its own dry run, its own go-ahead, its own key. Never reword a prompt to get past moderation unknownIt may have started. Send that batch again, unchanged, with the same key, once: Suno replays what started instead of charging for it twice No answer at all, or a timeout The same: the batch once more, unchanged, with the same key. If that fails too, read account-usage, tell the user what was spent, and stopThe call refuses what the dry run priced Stop and tell the user. Do not adjust and resend -
visuals-wait(ids: <up to 8 generation ids, comma-separated>, view: "summary"), again whilestatusisprocessing, ten times at most. A job that answersunreadwas skipped by a rate limit: wait itsretry_after_secondsand ask again. -
Let the user look. Each take has a
suno_url;visuals-show(ids: <asset_id>)lets you look at one to describe it or check it for stray marks. The first take to finish sits in the shot. The user may keep it, swap in the other take withsequence-update(id, shots: [{shot_id, asset_id}]), which is free, or have a shot made again, which is a new price and a new go-ahead. Never choose a take for them.
Step 7: The Animatic (free)
sequence-export(id: <sequence_id>). Keep theidit answers with. A409names a shot that is still being made or hasfailed: wait for it, or see Step 8's note on failed shots.visuals-wait(ids: <that id>, view: "summary"), again whileprocessing, ten times at most.- If the song is locked (Step 3), ask now. "Suno will only hand the video over once the song is unlocked, which costs one download credit. You have N." On a yes,
audio-download(id: <song.clip_id>, format: "mp3", confirm: true). On a no, give the user theeditor_url, where the cut plays on suno.com, and carry on without saving files. visuals-download(id: <the export's asset_id>), again while it answersprocessing, six times at most. Thensave_music_video(album_slug, track_slug, link: <that url>, shape, kind: "animatic").- The user watches it and judges the pacing. Changes to the cut are free:
sequence-updaterewrites a shot's notes and moves, trims, splits, deletes and adds shots withops, or the user does it at theeditor_url. After changes, read the Sequence again withsequence-get(id, view: "summary"), since shots after an edit move, and export again.
If the user chose the animatic alone, go to Step 9.
Step 8: Clips (paid by the second)
Only for the shots the user picked, and only once they are happy with the animatic.
- A prompt for each shot: what happens in it and how the camera moves. It opens on the shot's keyframe. Add
lip_sync: falseto a shot where no one should sing or mouth the words. - The model.
video-1unless the user asks for another. Always name it: left out, Suno uses the dearer one. - Price it. This spends nothing. In batches of 8, each written down:
sequence-generate(id, step: "clips", model, shots: [{shot_id, prompt, lip_sync?}], dry_run: true). Add upcredits, and check that every shot was priced on themodelyou named. The answer'snotessay what each shot is charged as: 9.44 seconds as 10. Say what that rounding comes to, but do not trim shots to save it: a trim shortens the video, moves every later shot off the music, and leaves the master too long to go under the picture. - State the cost and wait. "Clips for shots 1, 8 and 15 on video-1 (480p): 27 billed seconds, 405 Visuals credits. You have 978." The balance is the dry run's
visuals_credits_remaining. More than the balance → say so, and offer fewer shots. Do not generate until the user says go. Any change to the shots, the prompts or the model is a new price and a new go-ahead. - Generate, once a batch. Fix each batch's key first:
"{album_slug}/{track_slug}/music-video/clips/{batch number}/{UTC timestamp}". Send each batch exactly as it was priced, with its key and withoutdry_run. Suno starts about ten generations a minute, so a second batch may come backrate_limited. Handle each shot'sstatus, a timeout and a refusal as Step 6's table says. - Wait. Clips take minutes.
visuals-wait(ids, view: "summary")again whileprocessing, twenty times at most; then tell the user it is still running and how to carry on later: run this skill again, which finds the Sequence in Step 2 and waits for the shots still being made. It does not start them again. - A shot that failed reads
failedinsequence-get(id, view: "summary"), with afailure_reasonand ahint. Anysequence-update(id)call puts its keyframe back. Making it again is a new batch: a new price, a new go-ahead and a new key. Readaccount-usageand tell the user what the failed shot cost. - Let the user choose each shot's take, as in Step 6.
Step 9: Export and Save
sequence-export(id),visuals-wait, the lock question if it was not settled in Step 7, andvisuals-download, as in Step 7.save_music_video(album_slug, track_slug, link, shape, kind: "video"), withreplace: trueonly when the user said to replace an earlier video. When the track has a mastered file as long as the video, the master goes under the picture.saved: false→ report itserrorand stop; when it says the download stopped early, askvisuals-downloadfor the link again and save once more. Nothing that goes wrong here is a reason to generate anything again: the cut stays on Suno, at theeditor_url.
Step 10: Report
Call account-usage again and compare with Step 2.
MUSIC VIDEO — [NN] [Title]
Saved /path/to/music_videos/03-track-name-16x9.mp4 (1920x1080, 3:26)
Animatic /path/to/music_videos/03-track-name-16x9-animatic.mp4
Audio the master
Editor https://suno.com/visual/cmp_...
Spent 22 Visuals credits on keyframes, 405 on clips; 573 left
Spent comes from the balances, not from the quotes. If they differ, say so.
Remember
- Say what it would cost before any work. A whole song as clips is thousands of credits.
- Every paid call is priced first with
dry_run: true, stated, and waits for a go-ahead. A change is a new price. - And sent for real once, exactly as priced, with a key fixed beforehand. It is sent again only as Step 6's table allows, and a shot that holds or is making a take is never made again.
- Always name the model. Suno's defaults are its dearest: 50 a keyframe, 30 a second.
- The look, the cast and every take are the user's to choose.
- Never reword a prompt to get past moderation. One revision, for a named artist, character or person, approved by the user.
- The animatic comes before clips. The cut is free to change; clips are not.
- The keeper only. The video is made for the approved take.
- Unlocking a song can cost a download credit. Ask before
confirm: true.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |