# Kinetune

> Kinetune turns a song into release-ready video: lyric videos with word-synced lyrics and audio-reactive visuals in 9:16, 16:9, 1:1, 5–8 second Spotify Canvas loops designed from the song's cover, and AI music videos in which the artist performs the song, lip-synced, in shots cut between the lines and made from their photos. An AI director designs each video as a reusable "Look" in one of its lyric styles (kinetic typography, 3D objects that show the lyrics, lyrics behind the photo's subject or typed on a screen inside the scene, burn, ink, smoke and particle reveals), over an AI image (with scene changes or a parallax camera), an AI video loop, stock media or the artist's own photo or video; every video is quoted exactly in credits before anything is charged.

Kinetune is made in Québec, Canada. Use it in the web app at https://kinetune.com, through the REST API, from AI agents over MCP, from the command line, or in n8n. Support: https://kinetune.com/contact.

## Pricing

Videos are paid in credits. Every video shows its exact credit quote before anything is charged, credits are taken only when the video is delivered, and a failed render returns them. No plan limits quality or resolution.

- Solo: $10/month or $100/year (10 months' price), 1,000 credits a month, 50 GB of storage, 1 member, 1 render at a time and 1 AI music video at a time (their own limit, so they never hold up the others), render priority 1. For artists releasing a song or two a month: a lyric video and a Canvas for each.
- Creator: $20/month or $200/year (10 months' price), 2,500 credits a month, 100 GB of storage, 2 members, 1 render at a time and 1 AI music video at a time (their own limit, so they never hold up the others), render priority 2. For artists and creators releasing lyric videos and Canvases every month.
- Pro: $50/month or $500/year (10 months' price), 7,500 credits a month, 250 GB of storage, 5 members, 3 renders at a time and 2 AI music videos at a time (their own limit, so they never hold up the others), render priority 3, priority queue. For artists adding AI music videos to their releases, plus every lyric video and Canvas.
- Studio: $100/month or $1,000/year (10 months' price), 18,000 credits a month, 500 GB of storage, 15 members, 6 renders at a time and 3 AI music videos at a time (their own limit, so they never hold up the others), render priority 4, priority queue, priority support. For artists and teams making music videos, lyric videos and Canvases every month.
- Studio 45K: $250/month or $2,500/year (10 months' price), 45,000 credits a month, 1000 GB of storage, 25 members, 8 renders at a time and 4 AI music videos at a time (their own limit, so they never hold up the others), render priority 4, priority queue, priority support. For full-length music videos every month, plus every lyric video and Canvas.
- Studio 90K: $500/month or $5,000/year (10 months' price), 90,000 credits a month, 2000 GB of storage, 50 members, 10 renders at a time and 5 AI music videos at a time (their own limit, so they never hold up the others), render priority 4, priority queue, priority support. For teams making music videos for several artists every month, plus every lyric video and Canvas.
- When every render machine is busy, they are shared by render priority: an organization with priority 4 gets four parts of its videos rendered for every one of a priority-1 organization. A waiting video's `queue` says why it waits.
- Storage: songs, artist photos, uploads, Looks' media and videos count against the plan's storage; an upload or new video that doesn't fit answers 402 (code storage_full). Deleting or archiving frees space at once. After a plan ends, files are kept 90 days, then deleted.
- Every workspace needs a plan: uploading songs, photos and backgrounds and making videos answer 402 (code plan_required) without one. A workspace is an artist's (one artist) or a label's (a roster).
- Credit packs top up a plan's monthly credits (a plan is needed to buy them) and never expire: 1,000 credits for $12; 3,000 credits for $30; 7,500 credits for $70; 15,000 credits for $130; 30,000 credits for $250; 60,000 credits for $480.
- Plans change anytime: upgrades start at once (the difference for the rest of the period is charged), downgrades and monthly or yearly switches at the next renewal; a cancelled plan runs to the end of its paid period.
- What a 2:47 song costs: Lyric video of a 2:47 song · A Look you already have · one format: 82 credits; Lyric video of a 2:47 song · A new Look, AI image · one format: 216 credits; Lyric video of a 2:47 song · A new Look, AI video loop · one format: 443 credits; AI music video · 15 seconds · 480p: 294 credits; AI music video · 30 seconds · 480p: 572 credits; AI music video · 15 seconds · 768p: 457 credits; AI music video · 30 seconds · 768p: 899 credits; AI music video · 15 seconds · 1080p: 894 credits; AI music video · 30 seconds · 1080p: 1772 credits; Canvas for Spotify, 8 s · Stock video: 62 credits; Canvas for Spotify, 8 s · AI image, set in motion: 103 credits; Canvas for Spotify, 8 s · AI video · Standard: 612 credits; Canvas for Spotify, 8 s · AI video · High: 802 credits. Each extra format adds 12 credits per started half-minute.
- Payments are processed by Stripe. Details: https://kinetune.com/pricing

## Spotify Canvas spec

- What Spotify asks for: a vertical 9:16 loop of 3 to 8 seconds, 720 to 1080 px tall, as MP4 or JPG; without the song title or artist name, links, brands, Spotify's logo or heavy promotion, rapid cuts or flashing, or faces singing or talking to camera.
- What Kinetune delivers: a 5–8 second seamless loop (8 s unless you choose), 9:16 at 1080×1920 or 720×1280, MP4 (H.264, 30 fps), silent, under 8 MB. It follows the song's first chorus, so it moves at the song's tempo, with a layer of light designed for the song moving with that chorus over the picture or clip, and carries no text.
- Sources: AI video (`ai-video`): An image made from your cover’s world, brought to life by a video model. AI image (`ai-image`): An image made from your cover’s world, moved by our motion model. Stock photo (`stock-photo`): A stock photo moved by our motion model. Stock video (`stock-video`): A stock clip cut into a seamless loop.
- Styles (optional; the director picks one when omitted): `cinematic`, `dreamy`, `abstract`, `surreal`, `retro`, `minimal`, `dark`, `vibrant`, `nature`, `urban`.
- Kinetune makes the file and you add it: download the MP4, then in Spotify for Artists open Music, select the track and click Add Canvas. More: https://kinetune.com/spotify-canvas

## Music videos

- What it is: the song's artist performs the song, or a section of it, lip-synced in an AI music video made from their photos, with the original song as its sound. The artist needs photos first (`add_artist_photos`); without them the quote is refused.
- How it's made: a director looks at the cover, the section's lyrics and sound and the artist's photos (at most 8), picks the photos the artist is kept from, and writes the shot list: every shot, cut between the song's lines. The model makes the shots and edits them into the video, so check back on it rather than waiting.
- Models (`model`, default `one-take`), each with what it makes:
  - MiniMax H3 Max (`one-take`): MiniMax’s H3 Max video model: the artist performs your song, lip-synced, from two photos (the face and the outfit), in shots cut between the lines. Categories: Performance, Performance & story, Cinematic, Story, Surreal. Styles: Natural, Film, Golden hour, Neon night, Noir, Vintage, Dreamy. Formats: `9:16`, `16:9` or `1:1`. 0.25 to 10 minutes, in clips of about 15 seconds. Kit: up to 6 outfits, 6 places and 8 props a video, 7 places and props a clip. Qualities (`quality`, default `768p`; the same video, sharper and costlier): 480p (`480p`): about 3 minutes to make a minute of song, 1,128 credits a minute; 768p (`768p`): about 3 minutes to make a minute of song, 1,783 credits a minute; 1080p (`1080p`): about 3 minutes to make a minute of song, 3,528 credits a minute.
- The shot list first, free (`plan_music_video`, `POST /api/v1/music-video-plans`, about a minute, a limited number an hour): the same brief returns the concept, the photos it keeps the artist from, the world every shot keeps, and every shot with its times and lyrics. Show it to the person; `revise: {plan_id, note}` rewrites it with their note. Then quote and create with `plan_id`: the video is made from exactly that plan. Without one, the director plans it while it is made.
- The kit: the artist's outfits and the workspace's places and props, each a named piece with an `@handle` (`list_kit`, `GET /api/v1/kit`; `add_kit_piece`, `POST /api/v1/kit`, from an upload, a `file_url` or a `stock_id`, with an optional `crop` rectangle in fractions of the image). Mention one in `direction` ("the @blue-set on the @rooftop") and it is used exactly as it is; a handle that isn't in the kit is a `400` that names it. The director designs everything the brief leaves open.
- Scenes, for the places left open: `scenes: {mode: "invent"}` (default: the director imagines them) or `{mode: "stock"}` (it finds a real stock photo of each place, empty of people, and the artist is put into it). The plan lists its `places`; `swap_music_video_place` (`PATCH /api/v1/music-video-plans/{plan_id}/places/{place}`) puts another photo in a found place, free. Each picture a clip is given (an outfit, places, props) adds a little to the price.
- A lookbook before the shot list, optional (`design_music_video_shoot`, `POST /api/v1/music-video-lookbooks`, free, about a minute): the director designs what the brief leaves open as a lookbook (an outfit drawn on the artist, a place drawn empty, a prop alone) beside the brief's own pieces. Drawing its pictures costs credits: `render_music_video_lookbook` with `credits` = `price.draw.credits` (held, charged as each is drawn; one that fails is free). Keep or leave out pieces (`keep_music_video_lookbook_piece`), redraw one with a note (`redraw_music_video_lookbook_piece`) or all of the director's (`redesign_music_video_lookbook`), then `plan_music_video` with `lookbook_id`: the kept pieces are used as drawn and, with `save_to_kit` (default), join the kit.
- Backing vocals: words in (parentheses) in the song's lyrics are sung by someone else, off camera; the artist doesn't mouth them.
- Cast: `cast: {face_photo_id, outfit_photo_id}` picks the photos the artist is kept from (a sharp face with the mouth visible; the outfit and body worn throughout), for the slots the model has. Any left out, the director picks it; one photo can be both. A photo meant for one music video only goes up with `add_artist_photos` `hidden: true`: it stays off the artist's photos and its id works in `cast`.
- Categories (`category`, default `performance`): Performance (`performance`): The artist sings to camera in one place that suits the song. Performance & story (`intercut`): The artist sings to camera, cut against them living the song’s story. Cinematic (`cinematic`): A performance with a moving camera that travels through a location. Story (`story`): The artist acts out the song’s story while singing it. Surreal (`surreal`): The world around the artist transforms with the song, dreamlike and impossible.
- Styles (`style`, optional; the director picks one from the cover when omitted): Natural (`natural`): True-to-life color and light. Film (`film`): 35 mm film: grain, soft contrast and rich color. Golden hour (`golden-hour`): Warm, low sunlight and long shadows. Neon night (`neon-night`): Night with colored neon and wet reflections. Noir (`noir`): High-contrast black and white. Vintage (`vintage`): A faded retro grade with period detail. Dreamy (`dreamy`): Soft haze, glow and pastel light.
- One MP4 in one shape (`aspect_ratio`, default 9:16). The whole song, or a section with `trim`, within the model's length. `direction` (up to 2,000 characters) steers the idea and names kit pieces.
- Price: by its clips (setup, creative direction and making the clips); the quote is exact for the song, section and model.
- The video's `music_video` field gives its plan once it's made, in the same shape. Cancelling it also stops making it, and nothing is charged.

## How to

### Make a lyric video

1. Sign up at https://kinetune.com/signup and upload the song (MP3, WAV or M4A) with its square cover. Kinetune hears the lyrics and times every word itself; there are no lyrics to type.
2. Start from a Look (https://kinetune.com/looks) and hear the song in it, or let the director design a new one in a category and lyric style.
3. Pick the formats (9:16, 16:9, 1:1), the background and the part of the song (the whole song, or any part from 8 seconds).
4. Check the exact credit quote and confirm. Credits are taken when the video is delivered; a failed render gives them back. Download a 1080p MP4 for each format.

### Make a Spotify Canvas

1. Use the same upload: the cover sets the idea; the song sets the motion and the light that plays over it. Add photos of the artist to have them in the shot.
2. Choose Canvas, then a source (AI video, AI image, stock photo or stock video) and a style, or leave both to the director.
3. Check the quote, make it, download the MP4 and add it to the track in Spotify for Artists.

### Make a music video

1. Add a few photos of the artist: a clear face photo and one that shows the outfit work best. The cover still sets the look.
2. Choose Music video, then a category, the shape (9:16, 16:9 or 1:1) and the whole song or a section. Leave the style to the director, or pick one.
3. Read the director's plan, free: the idea and every shot with its lyrics. Ask for changes until you like it.
4. Check the quote and make it from that plan. It usually takes 5 to 20 minutes; download the MP4 when it's done.

### Make one through the API or MCP

1. Connect: an MCP client adds https://kinetune.com/mcp and signs in with OAuth; code calls https://kinetune.com/api/v1 with an organization API key.
2. Add the song: `create_artist`, then `create_song` (`POST /api/v1/songs`), then poll `get_song` (`GET /api/v1/songs/{song_id}`) until `analysis.status` is "ready". Reuse a ready song from `list_songs` (`GET /api/v1/songs`).
3. Price it: `quote_lyric_video` (`POST /api/v1/quotes`), `quote_canvas` (`POST /api/v1/quotes`) or `quote_music_video` (`POST /api/v1/quotes`) returns the exact credits and a `quote_id`. Show the person the price and get their go before making anything. Plan a music video first with `plan_music_video` (`POST /api/v1/music-video-plans`) (free): show the person the concept and shots, revise until they like it, then quote it with `song_id` and `plan_id`.
4. Make it: `create_lyric_video` (`POST /api/v1/videos`), `create_canvas` (`POST /api/v1/videos`) or `create_music_video` (`POST /api/v1/videos`) with the same input plus `quote_id`.
5. Wait for it: `wait_for_video` over MCP, or poll `get_video` (`GET /api/v1/videos/{video_id}`) until `status` is "completed"; it returns a download link per format. A music video usually takes 5 to 20 minutes, so check back with `get_video` (`GET /api/v1/videos/{video_id}`) or use a `callback_url`. Options (styles, categories, formats, prices) come from `get_options` (`GET /api/v1/options`).
The CLI runs the same steps: `kinetune songs create`, `kinetune quote canvas`, `kinetune create canvas`, `kinetune videos wait`.

## For developers and AI agents

- [Developer docs](https://kinetune.com/developers): REST API, MCP server, CLI, n8n, callbacks, errors and limits, and an [API reference](https://kinetune.com/developers/reference) with a page per operation.
- [OpenAPI 3.1 spec](https://kinetune.com/api/v1/openapi.json): the full REST API.
- [Full API reference for LLMs](https://kinetune.com/llms-full.txt): every operation with its parameters, scopes, CLI command and MCP tool.
- [Developer docs as Markdown](https://kinetune.com/developers/llms.txt): every docs page, each linked as Markdown (any docs page's Markdown is at /llms.mdx followed by its path).
- MCP server (Streamable HTTP): https://kinetune.com/mcp. ChatGPT, Claude, Cursor and VS Code connect with OAuth 2.1 sign-in; one tool per API operation, plus show_looks, show_songs and show_video, which apps with MCP Apps draw as Kinetune cards (quotes draw as an order ticket with a Make it button).
- REST API: https://kinetune.com/api/v1, `Authorization: Bearer kt_live_…` (an organization API key) or an OAuth access token.
- CLI for local agents and scripts: `npm install -g @kinetune/cli`, then `kinetune auth login`.
- n8n community node: `@kinetune/n8n-nodes-kinetune`.
- Agent skill and Claude Code plugin: [kinetune/skills](https://github.com/kinetune/skills). In Claude Code: `/plugin marketplace add kinetune/skills`; other agents: `npx skills add kinetune/skills`.
- Typical flow: upload a song, request a quote (exact credits), confirm the quote to start the video, then wait for the callback or poll until the download links are ready.
- Versions: `/api/v1` is stable and only grows (ignore unknown fields, expect new values). Anything that would break a caller is deprecated first, with `Deprecation` and `Sunset` headers, and keeps working at least 180 days. [Changelog](https://kinetune.com/developers/changelog).

## Pages

- [Home](https://kinetune.com/): Every video for your song: lyric videos, music videos and a Spotify Canvas, with live previews of every Look on a real song.
- [Lyric video maker](https://kinetune.com/lyric-video-maker): Make a lyric video from your song: words timed to the vocals, 34 lyric styles, every format, the exact price first.
- [Spotify Canvas maker](https://kinetune.com/spotify-canvas): Make a Spotify Canvas from your cover: a 5 to 8 second loop at Spotify's size, ready for Spotify for Artists.
- [Looks](https://kinetune.com/looks): Every Official and community Look, playing live on a sample song: start your lyric video from one.
- [Lyric styles](https://kinetune.com/styles): The 34 lyric styles: kinetic type, 3D lyrics, words behind you, on a screen in the scene, burn, ink, smoke and more.
- [Lyric videos for AI music](https://kinetune.com/ai-music): Lyric videos, music videos and a Spotify Canvas for songs made with Suno, Udio and other AI music tools.
- [Music video maker](https://kinetune.com/music-video-maker): AI music videos from your song and two photos: performance, story, cinematic and surreal, lip-synced to your vocal, the exact price first.
- [Pricing](https://kinetune.com/pricing): Plans, credit packs and what a video costs.
- [What's new](https://kinetune.com/whats-new): Everything new in Kinetune, newest first: features for lyric videos, music videos and Spotify Canvas, dated when they went live.
- [Developers](https://kinetune.com/developers): REST API, MCP server, CLI and n8n node, with the full API reference.
- [Press kit](https://kinetune.com/press): Kinetune's logo, screenshots, real videos, ready-to-use descriptions and the facts, free to use when writing about Kinetune.
- [Contact](https://kinetune.com/contact): Write to Kinetune: help, billing and refunds, press, partnerships or anything else. A person answers every message.
- [Support](https://kinetune.com/support): How to reach a person, and answers about billing, refunds and your account.
- [Terms of Service](https://kinetune.com/terms): The terms for using Kinetune.
- [Privacy Policy](https://kinetune.com/privacy): What personal information Kinetune collects and why.
- [Refund Policy](https://kinetune.com/refunds): When and how to get a refund.

## Lyric styles

A lyric style is how the words move on screen; a Look in that style brings its own picture, colors and type. 34 styles, each with a live sample at https://kinetune.com/styles. The id goes in `look.lyric_style`.

- [Showcase](https://kinetune.com/styles/showcase) (`showcase`): The release is the hero: cover, title and artist, with a karaoke line under them.
- [Block stack](https://kinetune.com/styles/block-stack) (`block-stack`): Words build into a bold justified block; short words grow huge.
- [Punch](https://kinetune.com/styles/punch) (`punch`): One huge word at a time, hitting on the beat, with the line underneath.
- [Depth scatter](https://kinetune.com/styles/depth-scatter) (`depth-scatter`): Words float in at different depths and sharpen into focus.
- [Neon](https://kinetune.com/styles/neon) (`neon`): Glowing tube-light lyrics with a spectrum glowing below.
- [Terminal](https://kinetune.com/styles/terminal) (`terminal`): Lyrics typed out line by line on a glowing screen, with a cursor.
- [Cinematic](https://kinetune.com/styles/cinematic) (`cinematic`): Elegant titles that breathe in and out of focus between cinema bars.
- [Player](https://kinetune.com/styles/player) (`player`): A music-app lyric sheet that scrolls with the song, with cover and progress bar.
- [Lo-fi](https://kinetune.com/styles/lo-fi) (`lo-fi`): Soft words drifting up over grain and dust, with a quiet progress bar.
- [Zine](https://kinetune.com/styles/zine) (`zine`): Raw stacked type with grit, RGB hits and scratches.
- [Glitch](https://kinetune.com/styles/glitch) (`glitch`): Digital lyrics that tear, split and flicker with the beat.
- [Pop art](https://kinetune.com/styles/pop-art) (`pop-art`): Chunky words that bounce in with hard shadows and highlighter boxes.
- [Dreamy](https://kinetune.com/styles/dreamy) (`dreamy`): A soft lyric sheet that drifts through haze and light leaks.
- [Chrome](https://kinetune.com/styles/chrome) (`chrome`): Polished metal lyrics that flip into place.
- [Visualizer](https://kinetune.com/styles/visualizer) (`visualizer`): The cover inside a circular spectrum, lyrics beneath it.
- [Minimal](https://kinetune.com/styles/minimal) (`minimal`): Clean centred lines; the sung word lights up.
- [Outline](https://kinetune.com/styles/outline) (`outline`): Hollow letters that fill in as each word is sung.
- [Messages](https://kinetune.com/styles/messages) (`messages`): Each line arrives as a chat message, typed as it is sung.
- [Vinyl](https://kinetune.com/styles/vinyl) (`vinyl`): Your cover spinning on a 3D turntable, the lyrics beside it.
- [Album](https://kinetune.com/styles/album) (`album`): Your cover floating in 3D over its reflection, lyrics beneath.
- [Retro TV](https://kinetune.com/styles/tv) (`tv`): A 3D CRT television typing your lyrics on its glowing screen.
- [Cube](https://kinetune.com/styles/cube) (`cube`): Each line printed on a face of a 3D cube that turns with the song.
- [Boombox](https://kinetune.com/styles/cassette) (`cassette`): A 3D boombox whose display scrolls your lyrics while the tape turns.
- [Phone](https://kinetune.com/styles/phone) (`phone`): Your lyrics arriving as messages on a 3D phone.
- [Glass](https://kinetune.com/styles/glass) (`glass`): Iridescent glass shapes drifting over your lyrics and bending them.
- [Embers](https://kinetune.com/styles/embers) (`embers`): Lines burn in from glowing edges and burn away to ash.
- [Ink](https://kinetune.com/styles/ink) (`ink`): Words bleed in like ink in water, then wash away.
- [Smoke](https://kinetune.com/styles/smoke) (`smoke`): Lyrics form out of smoke and drift away.
- [Stardust](https://kinetune.com/styles/stardust) (`stardust`): Each line swarms together out of glowing particles and blows away.
- [Drip](https://kinetune.com/styles/drip) (`drip`): Chromatic letters that smear and drip down, splitting on the beat.
- [Rainy window](https://kinetune.com/styles/rain) (`rain`): Lyrics behind a window streaked with rain.
- [On screen](https://kinetune.com/styles/screen) (`screen`): Your lyrics typed on a screen inside the scene: a phone, a monitor, a billboard.
- [Behind](https://kinetune.com/styles/behind) (`behind`): Giant words stacked behind the subject of your photo, the subject standing in front of them.
- [Big type](https://kinetune.com/styles/big-type) (`big-type`): Giant gradient words stacking up, with a spectrum along the floor.

## Look categories

A Look is a reusable lyric video design: lyric style, colors, fonts, the layout for each format and the background. Browse Official and community Looks at https://kinetune.com/looks, or have the director design a new one in a category (the id goes in `look.category`).

- [Release](https://kinetune.com/looks/category/release) (`release`): Bold announcement looks for a new single.
- [Fall](https://kinetune.com/looks/category/fall) (`fall`): Warm autumn colors and cozy textures.
- [Halloween](https://kinetune.com/looks/category/halloween) (`halloween`): Spooky nights, pumpkins and fog.
- [Christmas](https://kinetune.com/looks/category/christmas) (`christmas`): Snowy, glowing holiday looks.
- [Summer](https://kinetune.com/looks/category/summer) (`summer`): Sun, water and holiday energy.
- [Valentine's](https://kinetune.com/looks/category/valentines) (`valentines`): Romantic reds, roses and soft light.
- [Mood](https://kinetune.com/looks/category/mood) (`mood`): Cinematic scenes with a lyric quote.
- [Retro](https://kinetune.com/looks/category/retro) (`retro`): Vinyl, film grain and vintage type.
- [Synthwave](https://kinetune.com/looks/category/synthwave) (`synthwave`): Neon sunsets and night drives.
- [Street](https://kinetune.com/looks/category/street) (`street`): Concrete, graffiti and grit.
- [Nature](https://kinetune.com/looks/category/nature) (`nature`): Forests, mountains and open water.
- [Luxury](https://kinetune.com/looks/category/luxury) (`luxury`): Marble, gold and deep velvet.
- [Abstract](https://kinetune.com/looks/category/abstract) (`abstract`): Flowing color fields and gradients.
- [Minimal](https://kinetune.com/looks/category/minimal) (`minimal`): Quiet color and clean type.
- [Neon](https://kinetune.com/looks/category/neon) (`neon`): Glowing color in the dark.
- [Pop art](https://kinetune.com/looks/category/pop-art) (`pop-art`): Loud patterns and graphic color.
- [Lo-fi](https://kinetune.com/looks/category/lo-fi) (`lo-fi`): Cozy illustrated rooms, rainy windows and soft grain.
- [Grunge](https://kinetune.com/looks/category/grunge) (`grunge`): Torn paper, concrete and raw black-and-white grit.
- [Cosmic](https://kinetune.com/looks/category/cosmic) (`cosmic`): Nebulae, planets and deep-space light.
- [Cyber](https://kinetune.com/looks/category/cyber) (`cyber`): Cyberpunk streets, screens and digital glitches.
- [Dreamy](https://kinetune.com/looks/category/dreamy) (`dreamy`): Clouds, soft skies and hazy golden light.

## API reference

Base URL https://kinetune.com/api/v1. Each operation is also an MCP tool (named below) and a CLI command.

### Scopes

- `videos:read`: See videos, quotes and your credit balance
- `videos:write`: Quote, create, cancel, retry and delete videos (spends credits)
- `music:read`: See artists, their photos and songs
- `music:write`: Add, rename and archive artists and songs, upload songs and artist photos
- `library:read`: Browse Looks
- `library:write`: Rename, delete and publish your Looks
- `organizations:read`: See the workspaces you belong to
- `organizations:write`: Create workspaces you own, and rename or switch the type of one you own or run

### Account

#### Get the account

`GET /api/v1/account` · MCP tool `get_account` · CLI `kinetune account` · scopes `videos:read`, `music:read`, `library:read`

Returns the organization the credentials act for (the workspace, as the app calls it; type artist holds one artist, label a roster), how they authenticate and their scopes, the credit balance (available, monthly, top-ups) and its plan, if any: active says whether it lets the workspace create (without an active plan, creating answers 402 plan_required: tell the person to choose a plan in the app), storage (used_bytes against limit_bytes, what the plan allows: an upload or new video that does not fit answers 402 storage_full, and deleting videos or archiving songs frees space at once), where it is billed, when the period ends, and a downgrade or interval switch waiting for the renewal as scheduled_change. Monthly credits reset every month; top-ups never expire. Check it before creating anything.

#### List the options

`GET /api/v1/options` · MCP tool `get_options` · CLI `kinetune options` · scopes `videos:read`, `music:read`, `library:read`

Everything a request can choose from, with the credit table, and what's on sale (plans: each plan's monthly and yearly price in cents, monthly credits, limits and features, the recommended one marked highlighted, and shelf: everyday for lyric videos, Canvas and some AI music videos, studio for AI music videos every month; credit_packs: each pack's credits and price in cents). The catalog is set by Kinetune's admins and can change; a subscription keeps what it was bought with. Use it to pick a category or source and to explain prices.

#### List your organizations

`GET /api/v1/organizations` · MCP tool `list_organizations` · CLI `kinetune organizations list` · scopes `organizations:read`

Every organization (workspace, in the app) the signed-in person is a member of; with an API key, the member who created it (the key needs organizations:read). type is artist (one artist and its songs) or label (a roster of artists). current marks the organization these credentials act for. Each organization has its own plan, music, videos, Looks and credits: to work in another one, sign in again and pick it on the consent screen, or use an API key created in it.

#### Create an organization

`POST /api/v1/organizations` · MCP tool `create_organization` · CLI `kinetune organizations create` · scopes `organizations:write`

Creates an empty organization (a workspace, in the app) with the signed-in person as its owner; with an API key, the member who created the key (the key needs organizations:write). type artist is for one artist (add that artist next with create_artist; its songs then need no artist_id), label for a roster. It starts with no plan and no credits: the owner chooses a plan in the app before anything can be created in it. These credentials keep acting for their current organization: to work in the new one, sign in again and pick it, or create an API key in it.

Parameters:
- `name` (body, string, required): The workspace name, as people see it in the app (an artist workspace usually carries the artist name)
- `type` (body, "artist" | "label", required): artist: one artist and its songs; label: a roster of artists

#### Update the organization

`PATCH /api/v1/organization` · MCP tool `update_organization` · CLI `kinetune organizations update` · scopes `organizations:write`

Owners and admins only. An artist workspace can become a label any time; a label can become an artist workspace only while it has one artist or none (409 otherwise).

Parameters:
- `name` (body, string): The new workspace name
- `type` (body, "artist" | "label"): artist (one artist) or label (a roster)

### Artists and photos

#### List artists

`GET /api/v1/artists` · MCP tool `list_artists` · CLI `kinetune artists list` · scopes `music:read`, `videos:read`

Songs belong to an artist; create the artist first. Sorted by name, 50 per page by default: pass q to search by name, and limit/offset to page.

Parameters:
- `q` (query, string): Part of the artist name
- `limit` (query, integer 1–100): Results per page, 1-100 (default 50)
- `offset` (query, integer 0–9007199254740991): How many results to skip

#### Create an artist

`POST /api/v1/artists` · MCP tool `create_artist` · CLI `kinetune artists create` · scopes `music:write`, `videos:write`

Names are unique per organization (409 when taken). An artist workspace holds one artist: a second one is refused (409) until the workspace becomes a label (update_organization). Works without a plan, so onboarding can add the artist first.

Parameters:
- `name` (body, string, required): The artist name

#### Get an artist

`GET /api/v1/artists/{artist_id}` · MCP tool `get_artist` · CLI `kinetune artists get` · scopes `music:read`, `videos:read`

One artist

Parameters:
- `artist_id` (path, string, required): The artist id

#### Rename an artist

`PATCH /api/v1/artists/{artist_id}` · MCP tool `rename_artist` · CLI `kinetune artists rename` · scopes `music:write`, `videos:write`

Change an artist’s name

Parameters:
- `artist_id` (path, string, required): The artist id
- `name` (body, string, required): The new name

#### Archive an artist

`DELETE /api/v1/artists/{artist_id}` · MCP tool `archive_artist` · CLI `kinetune artists archive` · scopes `music:write`, `videos:write`

Refused (409) while the artist still has songs.

Parameters:
- `artist_id` (path, string, required): The artist id

#### Set the artist picture

`POST /api/v1/artists/{artist_id}/picture` · MCP tool `set_artist_picture` · CLI `kinetune artists picture` · scopes `music:write`, `videos:write`

The picture (image_url on the artist, a 512 px square) is cut from one of the artist’s photos; the photo itself is unchanged. The first photo becomes the picture automatically, centered. crop is in fractions of the photo (its url): x/y the top-left corner, size the side relative to the photo’s short side; leave it out to center.

Parameters:
- `artist_id` (path, string, required): The artist id
- `photo_id` (body, string, required): One of the artist’s photos (list_artist_photos)
- `crop` (body, object): The square to keep, in fractions of the photo; centered when omitted

#### List artist photos

`GET /api/v1/artists/{artist_id}/photos` · MCP tool `list_artist_photos` · CLI `kinetune artists photos list` · scopes `music:read`, `videos:read`

Photos keep the artist recognizable when a Look or Canvas shows them; the cover art stays the creative source. url is the photo upright at up to 1536 px (what the AI receives; width and height describe it), thumbnail_url a copy 320 px on its short side for grids.

Parameters:
- `artist_id` (path, string, required): The artist id

#### Add artist photos

`POST /api/v1/artists/{artist_id}/photos` · MCP tool `add_artist_photos` · CLI `kinetune artists photos add` · scopes `music:write`, `videos:write`

As many as your plan's storage holds (up to 20 an upload), at least 512 px on the short side, up to 15 MB each. hidden keeps them off the artist's photos, for photos meant for one music video only (pass their ids in its cast). Only with the rights to use them (rights_confirmed). They are identity references only: never shown publicly or used as they are. Each is kept upright at up to 1536 px, with a small thumbnail; the uploaded file itself is not kept. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `artist_id` (path, string, required): The artist id
- `photo_urls` (body, URL[] (1–20)): Public https URLs of the photos (or upload files with the CLI)
- `rights_confirmed` (body, true, required): You have the rights to use these photos of the artist
- `hidden` (body, boolean): true: only for a music video, kept off the artist's photos (default false)
- File upload `photos` (or `photo_urls` with a URL): Photos of the artist

#### Delete an artist photo

`DELETE /api/v1/artists/{artist_id}/photos/{photo_id}` · MCP tool `delete_artist_photo` · CLI `kinetune artists photos delete` · scopes `music:write`, `videos:write`

Remove one photo

Parameters:
- `artist_id` (path, string, required): The artist id
- `photo_id` (path, string, required): The photo id

#### List the kit

`GET /api/v1/kit` · MCP tool `list_kit` · CLI `kinetune kit list` · scopes `music:read`, `videos:read`

The kit is what a music video is made from besides the artist’s photos: outfits (an artist’s), places and props (the workspace’s, for every artist). Each has a name and an @handle; a music video brief (direction) that mentions @handle uses that piece exactly as it is, and the director designs the rest. With artist_id: the workspace's places and props and that artist's outfits (what a brief for their song can mention); without it, every artist's outfits too. url is the piece cropped, up to 1536 px (what the AI receives; width and height describe it), thumbnail_url a 320 px copy, source_url the image the crop is a rectangle of.

Parameters:
- `artist_id` (query, string): Only the workspace’s pieces and this artist’s outfits
- `kind` (query, "outfit" | "place" | "prop"): outfit, place or prop

#### Add a kit piece

`POST /api/v1/kit` · MCP tool `add_kit_piece` · CLI `kinetune kit add` · scopes `music:write`, `videos:write`

The kit is what a music video is made from besides the artist’s photos: outfits (an artist’s), places and props (the workspace’s, for every artist). Each has a name and an @handle; a music video brief (direction) that mentions @handle uses that piece exactly as it is, and the director designs the rest. An outfit needs artist_id; a place or prop is the workspace's. The image is an upload or file_url (JPEG, PNG or WebP, at least 512 px on its short side, up to 15 MB, with rights_confirmed) or a stock_id from search_stock (credited, no rights needed). crop keeps a rectangle of it (fractions; at least 256 px on its short side), for a prop cut out of a bigger photo. handle follows the name (Blue set → blue-set; -2 when taken) unless given. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `kind` (body, "outfit" | "place" | "prop", required): outfit (an artist’s), place or prop (the workspace’s)
- `name` (body, string, required): What it is called, e.g. Blue set
- `artist_id` (body, string): The artist an outfit belongs to (outfits only)
- `handle` (body, string): Its @handle (default: from the name)
- `description` (body, string): What it is, for the director (a stock photo’s caption by default)
- `crop` (body, object): The rectangle to keep, in fractions of the image: {"x","y","w","h"}; the whole image when omitted
- `file_url` (body, URL): A public https URL of the image (or upload a file with the CLI)
- `stock_id` (body, string): A stock photo id from search_stock instead of an image
- `rights_confirmed` (body, true): You have the rights to use the image (needed for an upload or file_url)
- File upload `file` (or `file_url` with a URL): The image of the piece

#### Get a kit piece

`GET /api/v1/kit/{kit_id}` · MCP tool `get_kit_piece` · CLI `kinetune kit get` · scopes `music:read`, `videos:read`

One outfit, place or prop

Parameters:
- `kit_id` (path, string, required): The kit piece id

#### Change a kit piece

`PATCH /api/v1/kit/{kit_id}` · MCP tool `update_kit_piece` · CLI `kinetune kit update` · scopes `music:write`, `videos:write`

crop is cut again from the image the piece was added from. Plans already made keep the pieces as they were planned.

Parameters:
- `kit_id` (path, string, required): The kit piece id
- `name` (body, string)
- `handle` (body, string)
- `description` (body, string)
- `crop` (body, object): The new rectangle, in fractions of the source image

#### Delete a kit piece

`DELETE /api/v1/kit/{kit_id}` · MCP tool `delete_kit_piece` · CLI `kinetune kit delete` · scopes `music:write`, `videos:write`

A plan that used it can’t be made any more: plan again.

Parameters:
- `kit_id` (path, string, required): The kit piece id

### Songs

#### List songs

`GET /api/v1/songs` · MCP tool `list_songs` · CLI `kinetune songs list` · scopes `music:read`, `videos:read`

A song must be analyzed (analysis.status "ready") before videos can be made. 50 per page by default: pass q to search, and limit/offset to page. cover_art.url is the cover at up to 1536 px (JPEG; width and height describe it), preview_url a 640 px and thumbnail_url a 160 px WebP. Image links are signed for 7 days and stay the same all day, so they can be cached.

Parameters:
- `artist_id` (query, string): Only this artist’s songs
- `q` (query, string): Part of the song title or artist name
- `limit` (query, integer 1–100): Results per page, 1-100 (default 50)
- `offset` (query, integer 0–9007199254740991): How many results to skip
- `status` (query, "pending" | "processing" | "ready" | "failed"): Only songs whose analysis has this status (ready = usable for videos)
- `sort` (query, "title" | "newest"): title (default): by artist then title; newest: latest uploads first

#### Upload a song

`POST /api/v1/songs` · MCP tool `create_song` · CLI `kinetune songs create` · scopes `music:write`, `videos:write`

Audio: MP3, WAV or M4A up to 250 MB. Cover: a square JPEG or PNG, 1000–6000 px (3000×3000 recommended), up to 20 MB; it is kept at 1536, 640 and 160 px, not as uploaded. The song is analyzed next (lyrics, beats, sections): poll get_song until analysis.status is "ready", usually about a minute. Pass lyrics (or set them later with set_song_lyrics) to have the videos spell every word right. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `artist_id` (body, string): The artist id. An artist workspace may leave it out: its songs are its artist's
- `title` (body, string, required): The song title
- `language` (body, string): Lyrics language (ISO 639-1, e.g. "en"); detected when omitted
- `audio_url` (body, URL): A public https URL of the master audio
- `cover_art_url` (body, URL): A public https URL of the square cover art
- `lyrics` (body, string): Optional. The song’s lyrics as text: plain (Suno-style [Verse]/[Chorus] tags and (x2) marks are fine), or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio: your text fixes misheard words and sets where lines break in videos. A part sung again (a chorus) can be written once; lyrics that don’t match what’s sung, or cover only part of it, are refused once the song is analyzed (get_song: analysis.lyrics.status "mismatch")
- File upload `audio` (or `audio_url` with a URL): Master audio (MP3, WAV or M4A)
- File upload `cover_art` (or `cover_art_url` with a URL): Square cover art (JPEG or PNG)

#### Get a song

`GET /api/v1/songs/{song_id}` · MCP tool `get_song` · CLI `kinetune songs get` · scopes `music:read`, `videos:read`

cover_art.url is the cover at up to 1536 px (JPEG; width and height describe it), preview_url a 640 px and thumbnail_url a 160 px WebP. Image links are signed for 7 days and stay the same all day, so they can be cached. analysis.lyrics.status says whose words its videos show: "transcribed" (as heard), "checked" (your lyrics, timed from the audio; corrected, added and kept count what checking did), "waiting" (your lyrics, checked once the analysis finishes) or "mismatch" (your lyrics didn’t match what’s sung, so the transcription is used).

Parameters:
- `song_id` (path, string, required): The song id

#### Rename a song

`PATCH /api/v1/songs/{song_id}` · MCP tool `rename_song` · CLI `kinetune songs rename` · scopes `music:write`, `videos:write`

Change a song’s title

Parameters:
- `song_id` (path, string, required): The song id
- `title` (body, string, required): The new title

#### Archive a song

`DELETE /api/v1/songs/{song_id}` · MCP tool `archive_song` · CLI `kinetune songs archive` · scopes `music:write`, `videos:write`

Remove a song (its videos stay)

Parameters:
- `song_id` (path, string, required): The song id

#### Get a song’s analysis

`GET /api/v1/songs/{song_id}/analysis` · MCP tool `get_song_analysis` · CLI `kinetune songs analysis` · scopes `music:read`, `videos:read`

parts lists where a video can start and end without cutting a word: each section (Verse 1, Chorus 1…), clips of about 15 seconds cut between the lines of long sections (kind "clip", parent: its section) and each verse with the chorus after it (kind "pair"); pass a part’s start and end as a video’s trim (start_seconds, end_seconds), picking one at least as long as the video type’s minimum (a lyric video 8 seconds, a music video 15). default_part is the one the app starts on: the sung part nearest 15 seconds. lyrics.text is the song’s lyrics to edit: yours as you gave them, or the transcription a line per phrase (lyrics.yours says which).

Parameters:
- `song_id` (path, string, required): The song id
- `min_seconds` (query, number 8–600): The parts for a video at least this long: a music video 15 (its clips are cut no shorter). Default 8, a lyric video

#### Analyze a song again

`POST /api/v1/songs/{song_id}/analysis` · MCP tool `reanalyze_song` · CLI `kinetune songs reanalyze` · scopes `music:write`, `videos:write`

Retry a failed analysis

Parameters:
- `song_id` (path, string, required): The song id

#### Set a song’s lyrics

`POST /api/v1/songs/{song_id}/lyrics` · MCP tool `set_song_lyrics` · CLI `kinetune songs set-lyrics` · scopes `music:write`, `videos:write`

The song’s lyrics as text: plain (Suno-style [Verse]/[Chorus] tags and (x2) marks are fine), or the contents of an SRT, WebVTT or LRC file. Every word is still timed from the audio: your text fixes misheard words and sets where lines break in videos. A part sung again (a chorus) can be written once; lyrics that don’t match what’s sung, or cover only part of it, are refused (409, the song unchanged). They are checked right away (analysis.lyrics in the answer says what changed), or once the analysis finishes if it hasn’t (202). Videos made from then on use them; videos already made stay as they are.

Parameters:
- `song_id` (path, string, required): The song id
- `lyrics` (body, string, required): The lyrics: text, or an SRT, WebVTT or LRC file’s contents

#### Remove a song’s lyrics

`DELETE /api/v1/songs/{song_id}/lyrics` · MCP tool `clear_song_lyrics` · CLI `kinetune songs clear-lyrics` · scopes `music:write`, `videos:write`

Videos made from then on show the words as transcribed.

Parameters:
- `song_id` (path, string, required): The song id

### Looks

#### List Looks

`GET /api/v1/looks` · MCP tool `list_looks` · CLI `kinetune looks list` · scopes `library:read`, `videos:read`

A Look is a complete, reusable lyric-video design. Pass its id as {"mode":"existing","id":…} to reuse it exactly. A Look that shows an artist (featured_artist) is private and only serves that artist's songs: choosing for a song, pass its artist_id to leave out Looks that show another artist.

Parameters:
- `scope` (query, "all" | "official" | "community" | "mine"): Which library; default all
- `category` (query, string): A category id from get_options
- `lyric_style` (query, string): A lyric style id from get_options (how the lyrics move)
- `artist_id` (query, string): The artist of the song you are choosing for: Looks that show another artist are left out
- `q` (query, string): Search words
- `sort` (query, "newest" | "popular")
- `limit` (query, integer 1–100)
- `offset` (query, integer 0–9007199254740991)

#### Get a Look

`GET /api/v1/looks/{look_id}` · MCP tool `get_look` · CLI `kinetune looks get` · scopes `library:read`, `videos:read`

backgrounds.portrait and backgrounds.landscape are the background plates the video uses; backgrounds.previews has 480 px wide copies of them for thumbnails (null for a Look without a photo or video background).

Parameters:
- `look_id` (path, string, required): The Look id

#### Rename a Look

`PATCH /api/v1/looks/{look_id}` · MCP tool `rename_look` · CLI `kinetune looks rename` · scopes `library:write`, `videos:write`

Rename one of your Looks

Parameters:
- `look_id` (path, string, required): The Look id
- `name` (body, string, required): The new name

#### Delete a Look

`DELETE /api/v1/looks/{look_id}` · MCP tool `delete_look` · CLI `kinetune looks delete` · scopes `library:write`, `videos:write`

Remove one of your Looks (videos made with it stay)

Parameters:
- `look_id` (path, string, required): The Look id

#### Publish or unpublish a Look

`POST /api/v1/looks/{look_id}/visibility` · MCP tool `set_look_visibility` · CLI `kinetune looks visibility` · scopes `library:write`, `videos:write`

Public Looks join the Community library under your @username. A Look that shows your artist stays private (409).

Parameters:
- `look_id` (path, string, required): The Look id
- `visibility` (body, "public" | "private", required)

#### Upload a background

`POST /api/v1/backgrounds` · MCP tool `upload_background` · CLI `kinetune backgrounds upload` · scopes `library:write`, `videos:write`

Photo: JPEG, PNG or WebP, at least 720 px on the short side, up to 25 MB. Video: MP4, MOV or WebM, 4–180 seconds, at least 720 px on the short side, up to 300 MB; it becomes a seamless loop of up to 20 s. Only with the rights to use it. Then quote a lyric video with look {"mode":"new","category":"…","background":{"source":"upload-photo" or "upload-video","upload_id":"…"},"visibility":"private"}. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `file_url` (body, URL): A public https URL of the photo or video
- `rights_confirmed` (body, true, required): You have the rights to use this photo or video
- File upload `file` (or `file_url` with a URL): Your photo or video

#### Search stock media

`GET /api/v1/stock` · MCP tool `search_stock` · CLI `kinetune stock search` · scopes `videos:read`, `videos:write`, `library:read`

24 results a page. Pass an item's id as look.background.stock_id (source "stock-photo" or "stock-video") or as a Canvas's stock_id to use it instead of the director's pick, and credit the photographer (credit) wherever you show it. orientation: portrait for 9:16 and 1:1, landscape when 16:9 is among the formats (a Canvas is portrait). Clips too short for the loop are left out: pass seconds for a Canvas. thumbnail_url is a 480 px still, preview_url a 1280 px one (the photo, or the clip's poster), preview_video_url a small MP4 of a clip.

Parameters:
- `kind` (query, "photo" | "video", required): photo for stock-photo, video for stock-video
- `q` (query, string, required): Search words, e.g. "foggy pine forest"
- `orientation` (query, "portrait" | "landscape"): Default portrait
- `page` (query, integer 1–50): Default 1; next_page says whether there are more
- `seconds` (query, integer 5–8): Clips for a Canvas of this length (5–8); omit for a Look's loop

### Quotes and videos

#### Quote a lyric video

`POST /api/v1/quotes` · MCP tool `quote_lyric_video` · CLI `kinetune quote lyric-video` · scopes `videos:write`, `videos:read`

Returns quote_id, credits (total), credits_per_video and a breakdown. Always quote first and tell the user the credits before creating; credits are reserved at creation and charged only when the video is delivered. A quote is valid for 30 minutes.

Parameters:
- `song_id` (body, string, required): The song id
- `variations` (body, integer 1–4, default 1): 1–4 different New Looks, one video each (an Existing Look renders one)
- `callback_url` (body, string): An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
- `metadata` (body, object): Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
- `look` (body, object, required): {"mode":"existing","id":"look_…"} to reuse a saved Look (add "lyric_style" to render it in another lyric style, at no extra cost), or {"mode":"new","category":"…","lyric_style":"…","background":{"source":"ai-image","quality":"high"},"visibility":"private","direction":"…"} to have one designed (background.source "upload-photo"/"upload-video" with background.upload_id from upload_background designs it around your own media; such a Look stays private. "stock-photo"/"stock-video" with background.stock_id from search_stock uses that stock photo or clip instead of the director's pick). lyric_style (optional, from get_options) sets how the lyrics are presented and animated: block-stack, punch, player, neon, terminal, cinematic… Omit it and the director picks one. background.scenes (2–4, AI image only) makes that many shots of the same world that cut on the song's sections, each priced like the first. background.references "stock" (AI image or AI video, default "none") with feature_artist "always" makes the background one real stock photo of a place the director picks, with the artist put into it and restyled a little for the Look; no extra cost. The singer is left out unless asked: feature_artist "always" (default "never") makes them the subject of the background, recognizable from their artist photos (add_artist_photos); it needs an AI image or AI video background, a private Look and display.cover false (the cover would hide them), and that Look then only serves this artist's songs. A saved Look that shows an artist (featured_artist) only serves that artist's songs, also with display.cover false
- `aspect_ratios` (body, "9:16" | "16:9" | "1:1"[] (1–3), default ["9:16"]): Formats to render, each its own file: "9:16" (vertical), "16:9" (wide), "1:1" (square)
- `display` (body, object, default {"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true}): Which elements show (title, artist, cover, lyrics, badges, headline) and their sizes. cover must be false to show the artist in the background
- `trim` (body, object): Render only this section of the song (at least 8 seconds). Best: a part from get_song_analysis (parts[]: its start and end never cut a word)

#### Quote a Canvas

`POST /api/v1/quotes` · MCP tool `quote_canvas` · CLI `kinetune quote canvas` · scopes `videos:write`, `videos:read`

Returns quote_id, credits and a breakdown. Always quote first and tell the user the credits before creating; credits are reserved at creation and charged only when the video is delivered.

Parameters:
- `song_id` (body, string, required): The song id
- `variations` (body, integer 1–4, default 1): 1–4 different Canvases
- `callback_url` (body, string): An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
- `metadata` (body, object): Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
- `source` (body, "ai-video" | "ai-image" | "stock-photo" | "stock-video", default "ai-video"): ai-video (default), ai-image, stock-photo or stock-video
- `quality` (body, "standard" | "high", default "standard"): AI video model tier: standard or high
- `resolution` (body, "720p" | "1080p", default "1080p"): 1080p (1080×1920) or 720p
- `style` (body, "cinematic" | "dreamy" | "abstract" | "surreal" | "retro" | "minimal" | "dark" | "vibrant" | "nature" | "urban"): Optional visual style
- `direction` (body, string): Optional mood, motifs or references; the concept still comes from the cover
- `feature_artist` (body, "auto" | "always" | "never", default "auto"): Whether the Canvas shows the artist: auto (the director decides), always or never (AI sources; needs artist photos for "always")
- `seconds` (body, integer 5–8, default 8): Canvas length in whole seconds, 5–8 (default 8). Spotify loops it, so no part of the song is chosen
- `stock_id` (body, string): With a stock source: the stock photo or video (search_stock with seconds) to use instead of the director's pick

#### Write a music video shot list

`POST /api/v1/music-video-plans` · MCP tool `plan_music_video` · CLI `kinetune plan music-video` · scopes `videos:write`

Free (a limited number an hour). Takes about a minute. Returns a plan: the concept, the face and outfit photos, and its shots (cut between the song's lines, up to about 14 seconds each) with their lyrics and how each comes in (a cut, the director's transition, or carrying on in a continuous take). Show it to the user, rewrite it with revise until they like it, then quote_music_video and create_music_video with its plan_id.

Parameters:
- `song_id` (body, string, required): The song; its artist performs the video and needs photos (add_artist_photos)
- `model` (body, "one-take", default "one-take"): The music video model: one-take (default; MiniMax H3 Max, the artist lip-synced in shots cut between the song's lines). get_options lists the models with the categories, styles, formats, takes and length each makes
- `category` (body, "performance" | "intercut" | "cinematic" | "story" | "surreal", default "performance"): performance (default), intercut, cinematic, story or surreal
- `style` (body, "natural" | "film" | "golden-hour" | "neon-night" | "noir" | "vintage" | "dreamy"): Optional look: natural, film, golden-hour, neon-night, noir, vintage or dreamy; omitted, the director picks one from the cover
- `aspect_ratio` (body, "9:16" | "16:9" | "1:1", default "9:16"): "9:16" (default), "16:9" or "1:1"
- `trim` (body, object): Only 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)
- `direction` (body, string): Optional 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. An unknown handle answers 400
- `cast` (body, object): The two photos the artist is kept from: face_photo_id (a sharp face, mouth visible) and outfit_photo_id (the outfit and body worn throughout); either left out, the director picks it. One photo can be both; hidden photos (add_artist_photos hidden) work too
- `scenes` (body, object, default {"mode":"invent"}): Where 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
- `lookbook_id` (body, string): A lookbook (design_music_video_shoot) whose kept, drawn pieces the video uses like the kit pieces the direction mentions; its idea leads the director
- `takes` (body, "cuts" | "continuous", default "cuts"): How the shots meet: "cuts" (default: shots meet between the song's lines like an edit, with a cut or the transition the director picks at each join: dissolve, dip to black, flash or whip; ask for them, or for none, in direction) 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)
- `revise` (body, object): Rewrite an earlier plan of this song: {"plan_id":"plan_…","note":"what to change"} (the next draft)

#### Change a place's photo

`PATCH /api/v1/music-video-plans/{plan_id}/places/{place}` · MCP tool `swap_music_video_place` · CLI `kinetune plans swap-place` · scopes `videos:write`

Returns the next draft: the same shot list, set in this photo (no director call, free). Pick a photo of the same kind of place, with no people, from search_stock.

Parameters:
- `plan_id` (path, string, required): The plan id (plan_…)
- `place` (path, integer 1–9007199254740991, required): The place's number (places[].index)
- `stock_id` (body, string, required): A stock photo id from search_stock

#### Design a music video lookbook

`POST /api/v1/music-video-lookbooks` · MCP tool `design_music_video_shoot` · CLI `kinetune lookbook design` · scopes `videos:write`

Optional, before the shot list (plan_music_video). Free to design (a limited number an hour), about a minute: returns a lookbook whose pieces are the brief's own kit pieces (yours, used as they are) and the director's designs (an outfit drawn on the artist, a place drawn empty, a prop alone), not drawn yet. price.draw.credits is what drawing them costs: tell the user, then render_music_video_lookbook after their go. Same brief as plan_music_video. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `song_id` (body, string, required): The song; its artist performs the video and needs photos (add_artist_photos)
- `model` (body, "one-take", default "one-take"): The music video model: one-take (default; MiniMax H3 Max, the artist lip-synced in shots cut between the song's lines). get_options lists the models with the categories, styles, formats, takes and length each makes
- `category` (body, "performance" | "intercut" | "cinematic" | "story" | "surreal", default "performance"): performance (default), intercut, cinematic, story or surreal
- `style` (body, "natural" | "film" | "golden-hour" | "neon-night" | "noir" | "vintage" | "dreamy"): Optional look: natural, film, golden-hour, neon-night, noir, vintage or dreamy; omitted, the director picks one from the cover
- `aspect_ratio` (body, "9:16" | "16:9" | "1:1", default "9:16"): "9:16" (default), "16:9" or "1:1"
- `trim` (body, object): Only 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)
- `direction` (body, string): Optional 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. An unknown handle answers 400
- `cast` (body, object): The two photos the artist is kept from: face_photo_id (a sharp face, mouth visible) and outfit_photo_id (the outfit and body worn throughout); either left out, the director picks it. One photo can be both; hidden photos (add_artist_photos hidden) work too
- `scenes` (body, object, default {"mode":"invent"}): Where 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
- `takes` (body, "cuts" | "continuous", default "cuts"): How the shots meet: "cuts" (default: shots meet between the song's lines like an edit, with a cut or the transition the director picks at each join: dissolve, dip to black, flash or whip; ask for them, or for none, in direction) 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)

#### Get a lookbook

`GET /api/v1/music-video-lookbooks/{lookbook_id}` · MCP tool `get_music_video_lookbook` · CLI `kinetune lookbook get` · scopes `videos:read`

status is proposed (not drawn), rendering (being drawn: check back in about a minute), ready or failed. Each piece has its picture (image_url) once drawn, kept (true unless left out) and whether it is yours. price: per picture, to draw the rest (draw) and to redesign the director's pieces (redesign).

Parameters:
- `lookbook_id` (path, string, required): The lookbook id (lookbook_…)

#### Save a lookbook to the kit or not

`PATCH /api/v1/music-video-lookbooks/{lookbook_id}` · MCP tool `update_music_video_lookbook` · CLI `kinetune lookbook update` · scopes `videos:write`

save_to_kit true (default): the kept pieces become kit pieces of the workspace and the artist; false: they are used for that video only.

Parameters:
- `lookbook_id` (path, string, required): The lookbook id
- `save_to_kit` (body, boolean, required)

#### Draw a lookbook

`POST /api/v1/music-video-lookbooks/{lookbook_id}/render` · MCP tool `render_music_video_lookbook` · CLI `kinetune lookbook render` · scopes `videos:write`

credits is the price the user agreed to (price.draw.credits); a different price answers 409 with the current one. The credits are held, then charged as pictures are drawn; one that fails isn't charged. Poll get_music_video_lookbook until status is ready.

Parameters:
- `lookbook_id` (path, string, required): The lookbook id
- `credits` (body, integer, required): The price shown (price.draw.credits)

#### Redesign a lookbook

`POST /api/v1/music-video-lookbooks/{lookbook_id}/redesign` · MCP tool `redesign_music_video_lookbook` · CLI `kinetune lookbook redesign` · scopes `videos:write`

The user's own pieces stay. credits: price.redesign.credits.

Parameters:
- `lookbook_id` (path, string, required): The lookbook id
- `note` (body, string, required): What to change
- `credits` (body, integer, required): The price shown (price.redesign.credits)

#### Keep or leave out a lookbook piece

`PATCH /api/v1/music-video-lookbooks/{lookbook_id}/pieces/{piece}` · MCP tool `keep_music_video_lookbook_piece` · CLI `kinetune lookbook keep` · scopes `videos:write`

Whether a piece goes into the video

Parameters:
- `lookbook_id` (path, string, required): The lookbook id
- `piece` (path, integer 1–9007199254740991, required): The piece's number (pieces[].index)
- `kept` (body, boolean, required)

#### Redraw a lookbook piece

`POST /api/v1/music-video-lookbooks/{lookbook_id}/pieces/{piece}/redraw` · MCP tool `redraw_music_video_lookbook_piece` · CLI `kinetune lookbook redraw` · scopes `videos:write`

credits: price.credits_per_picture.

Parameters:
- `lookbook_id` (path, string, required): The lookbook id
- `piece` (path, integer 1–9007199254740991, required): The piece's number
- `note` (body, string): What to change: "warmer light, nobody else"
- `credits` (body, integer, required): The price shown (price.credits_per_picture)

#### Get a music video plan

`GET /api/v1/music-video-plans/{plan_id}` · MCP tool `get_music_video_plan` · CLI `kinetune plans get` · scopes `videos:read`

A plan made earlier

Parameters:
- `plan_id` (path, string, required): The plan id (plan_…)

#### Quote a music video

`POST /api/v1/quotes` · MCP tool `quote_music_video` · CLI `kinetune quote music-video` · scopes `videos:write`, `videos:read`

Returns quote_id, credits and a breakdown; the price follows the section's length (clips of about 15 seconds). The song's artist performs it, so the artist needs photos. Always quote first and tell the user the credits before creating; credits are reserved at creation and charged only when the video is delivered.

Parameters:
- `song_id` (body, string, required): The song; its artist performs the video and needs photos (add_artist_photos)
- `variations` (body, integer 1–4, default 1): 1–4 different music videos
- `callback_url` (body, string): An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
- `metadata` (body, object): Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
- `model` (body, "one-take", default "one-take"): The music video model: one-take (default; MiniMax H3 Max, the artist lip-synced in shots cut between the song's lines). get_options lists the models with the categories, styles, formats, takes and length each makes
- `category` (body, "performance" | "intercut" | "cinematic" | "story" | "surreal", default "performance"): performance (default: sings to camera in one place), intercut (performance cut against the artist living the song's story), cinematic (a moving camera through a location), story (acts out the song's story) or surreal (the world transforms with the song). get_options lists the ones each model makes
- `style` (body, "natural" | "film" | "golden-hour" | "neon-night" | "noir" | "vintage" | "dreamy"): Optional look: natural, film, golden-hour, neon-night, noir, vintage or dreamy. Omit it and the director picks one from the cover
- `aspect_ratio` (body, "9:16" | "16:9" | "1:1", default "9:16"): The one format of the file: "9:16" (default, vertical), "16:9" (wide) or "1:1" (square)
- `trim` (body, object): Perform only this section of the song (15 seconds to 10 minutes); omitted, the whole song (15 seconds to 10 minutes long). The price follows its length. Best: a part from get_song_analysis (parts[]: its start and end never cut a word)
- `direction` (body, string): Optional 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. An unknown handle answers 400
- `cast` (body, object): The two photos the artist is kept from: face_photo_id (a sharp face, mouth visible) and outfit_photo_id (the outfit and body worn throughout); either left out, the director picks it. One photo can be both; hidden photos (add_artist_photos hidden) work too
- `scenes` (body, object, default {"mode":"invent"}): Where 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
- `lookbook_id` (body, string): A lookbook (design_music_video_shoot) whose kept, drawn pieces the video uses like the kit pieces the direction mentions; its idea leads the director
- `takes` (body, "cuts" | "continuous", default "cuts"): How the shots meet: "cuts" (default: shots meet between the song's lines like an edit, with a cut or the transition the director picks at each join: dissolve, dip to black, flash or whip; ask for them, or for none, in direction) 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)
- `plan_id` (body, string): Make the video from this plan (plan_music_video): its brief replaces the one sent, so send song_id and plan_id. Omitted, the director plans it while it is made
- `quality` (body, "480p" | "768p" | "1080p", default "768p"): The resolution it is made at: one of the qualities get_options lists for the model (768p by default; 1080p is the same video sharper for about twice the credits); not part of the plan, so a plan is made in any quality. get_options lists each model's qualities with about how long each takes; credits.music_video.models has a minute by model and quality

#### Create a lyric video

`POST /api/v1/videos` · MCP tool `create_lyric_video` · CLI `kinetune create lyric-video` · scopes `videos:write`

Send the same request as the quote plus its quote_id. Returns the video ids at once; poll get_video until status is completed (or failed). Each video has one file per format. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `song_id` (body, string, required): The song id
- `variations` (body, integer 1–4, default 1): 1–4 different New Looks, one video each (an Existing Look renders one)
- `callback_url` (body, string): An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
- `metadata` (body, object): Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
- `look` (body, object, required): {"mode":"existing","id":"look_…"} to reuse a saved Look (add "lyric_style" to render it in another lyric style, at no extra cost), or {"mode":"new","category":"…","lyric_style":"…","background":{"source":"ai-image","quality":"high"},"visibility":"private","direction":"…"} to have one designed (background.source "upload-photo"/"upload-video" with background.upload_id from upload_background designs it around your own media; such a Look stays private. "stock-photo"/"stock-video" with background.stock_id from search_stock uses that stock photo or clip instead of the director's pick). lyric_style (optional, from get_options) sets how the lyrics are presented and animated: block-stack, punch, player, neon, terminal, cinematic… Omit it and the director picks one. background.scenes (2–4, AI image only) makes that many shots of the same world that cut on the song's sections, each priced like the first. background.references "stock" (AI image or AI video, default "none") with feature_artist "always" makes the background one real stock photo of a place the director picks, with the artist put into it and restyled a little for the Look; no extra cost. The singer is left out unless asked: feature_artist "always" (default "never") makes them the subject of the background, recognizable from their artist photos (add_artist_photos); it needs an AI image or AI video background, a private Look and display.cover false (the cover would hide them), and that Look then only serves this artist's songs. A saved Look that shows an artist (featured_artist) only serves that artist's songs, also with display.cover false
- `aspect_ratios` (body, "9:16" | "16:9" | "1:1"[] (1–3), default ["9:16"]): Formats to render, each its own file: "9:16" (vertical), "16:9" (wide), "1:1" (square)
- `display` (body, object, default {"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true}): Which elements show (title, artist, cover, lyrics, badges, headline) and their sizes. cover must be false to show the artist in the background
- `trim` (body, object): Render only this section of the song (at least 8 seconds). Best: a part from get_song_analysis (parts[]: its start and end never cut a word)
- `quote_id` (body, uuid, required): The quote_id from the matching quote: the request must be identical

#### Create a Canvas

`POST /api/v1/videos` · MCP tool `create_canvas` · CLI `kinetune create canvas` · scopes `videos:write`

Send the same request as the quote plus its quote_id. Returns the video ids at once; poll get_video until status is completed. Upload the file in Spotify for Artists. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `song_id` (body, string, required): The song id
- `variations` (body, integer 1–4, default 1): 1–4 different Canvases
- `callback_url` (body, string): An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
- `metadata` (body, object): Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
- `source` (body, "ai-video" | "ai-image" | "stock-photo" | "stock-video", default "ai-video"): ai-video (default), ai-image, stock-photo or stock-video
- `quality` (body, "standard" | "high", default "standard"): AI video model tier: standard or high
- `resolution` (body, "720p" | "1080p", default "1080p"): 1080p (1080×1920) or 720p
- `style` (body, "cinematic" | "dreamy" | "abstract" | "surreal" | "retro" | "minimal" | "dark" | "vibrant" | "nature" | "urban"): Optional visual style
- `direction` (body, string): Optional mood, motifs or references; the concept still comes from the cover
- `feature_artist` (body, "auto" | "always" | "never", default "auto"): Whether the Canvas shows the artist: auto (the director decides), always or never (AI sources; needs artist photos for "always")
- `seconds` (body, integer 5–8, default 8): Canvas length in whole seconds, 5–8 (default 8). Spotify loops it, so no part of the song is chosen
- `stock_id` (body, string): With a stock source: the stock photo or video (search_stock with seconds) to use instead of the director's pick
- `quote_id` (body, uuid, required): The quote_id from the matching quote: the request must be identical

#### Create a music video

`POST /api/v1/videos` · MCP tool `create_music_video` · CLI `kinetune create music-video` · scopes `videos:write`

Send the same request as the quote plus its quote_id. Returns the video ids at once; poll get_video until status is completed. It takes about 5 minutes for a minute of song, longer for the whole song. Needs an active plan (402 plan_required without one; get_account: plan.active) and room in its storage (402 storage_full when it would not fit; get_account: storage).

Parameters:
- `song_id` (body, string, required): The song; its artist performs the video and needs photos (add_artist_photos)
- `variations` (body, integer 1–4, default 1): 1–4 different music videos
- `callback_url` (body, string): An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value
- `metadata` (body, object): Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value
- `model` (body, "one-take", default "one-take"): The music video model: one-take (default; MiniMax H3 Max, the artist lip-synced in shots cut between the song's lines). get_options lists the models with the categories, styles, formats, takes and length each makes
- `category` (body, "performance" | "intercut" | "cinematic" | "story" | "surreal", default "performance"): performance (default: sings to camera in one place), intercut (performance cut against the artist living the song's story), cinematic (a moving camera through a location), story (acts out the song's story) or surreal (the world transforms with the song). get_options lists the ones each model makes
- `style` (body, "natural" | "film" | "golden-hour" | "neon-night" | "noir" | "vintage" | "dreamy"): Optional look: natural, film, golden-hour, neon-night, noir, vintage or dreamy. Omit it and the director picks one from the cover
- `aspect_ratio` (body, "9:16" | "16:9" | "1:1", default "9:16"): The one format of the file: "9:16" (default, vertical), "16:9" (wide) or "1:1" (square)
- `trim` (body, object): Perform only this section of the song (15 seconds to 10 minutes); omitted, the whole song (15 seconds to 10 minutes long). The price follows its length. Best: a part from get_song_analysis (parts[]: its start and end never cut a word)
- `direction` (body, string): Optional 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. An unknown handle answers 400
- `cast` (body, object): The two photos the artist is kept from: face_photo_id (a sharp face, mouth visible) and outfit_photo_id (the outfit and body worn throughout); either left out, the director picks it. One photo can be both; hidden photos (add_artist_photos hidden) work too
- `scenes` (body, object, default {"mode":"invent"}): Where 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
- `lookbook_id` (body, string): A lookbook (design_music_video_shoot) whose kept, drawn pieces the video uses like the kit pieces the direction mentions; its idea leads the director
- `takes` (body, "cuts" | "continuous", default "cuts"): How the shots meet: "cuts" (default: shots meet between the song's lines like an edit, with a cut or the transition the director picks at each join: dissolve, dip to black, flash or whip; ask for them, or for none, in direction) 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)
- `plan_id` (body, string): Make the video from this plan (plan_music_video): its brief replaces the one sent, so send song_id and plan_id. Omitted, the director plans it while it is made
- `quality` (body, "480p" | "768p" | "1080p", default "768p"): The resolution it is made at: one of the qualities get_options lists for the model (768p by default; 1080p is the same video sharper for about twice the credits); not part of the plan, so a plan is made in any quality. get_options lists each model's qualities with about how long each takes; credits.music_video.models has a minute by model and quality
- `quote_id` (body, uuid, required): The quote_id from the matching quote: the request must be identical

#### List videos

`GET /api/v1/videos` · MCP tool `list_videos` · CLI `kinetune videos list` · scopes `videos:read`

A page at a time (limit, default 50): next_cursor is null on the last page, otherwise pass it as cursor for the next one with the same filters. counts says how many videos match song_id, artist_id and q: all, and by type (lyric_video, canvas, music_video). Each video's outputs carry aspect_ratio, poster_url, poster_seconds and web_url (for thumbnails and previews); get_video has the download links. A video that is waiting has queue: why (plan_limit or render_capacity), its place in line or about how long.

Parameters:
- `song_id` (query, string): Only this song’s videos
- `artist_id` (query, string): Only videos of this artist’s songs
- `type` (query, "lyric-video" | "canvas" | "music-video")
- `q` (query, string): Search the song title, artist name, Look name or video id
- `limit` (query, integer 1–100)
- `cursor` (query, string): next_cursor from the previous page

#### Get a video

`GET /api/v1/videos/{video_id}` · MCP tool `get_video` · CLI `kinetune videos get` · scopes `videos:read`

status is queued, processing, completed, failed or cancelled. While it waits, queue says why: plan_limit (the organization already makes as many videos at once as its plan allows; position is its place in line) or render_capacity (every render machine is busy; estimated_wait_seconds is about how long). Completed videos have outputs with download_url (full quality), web_url (720p) and poster_url, signed for 7 days. A lyric video's poster is a frame with one whole lyric line on screen (the hook when it can be), ready to set as the thumbnail where you post it; a Canvas's is its first frame; a music video's a frame of its first seconds. poster_seconds says where in that file the poster was cut, for posts that take a cover frame offset instead of an image (TikTok); null on videos made before it was kept. Failed videos have error and error_code; AI_VIDEO_UNAVAILABLE means the AI video couldn’t be made for a reason on our side, so make it again later.

Parameters:
- `video_id` (path, string, required): The video id

#### Cancel a video

`POST /api/v1/videos/{video_id}/cancel` · MCP tool `cancel_video` · CLI `kinetune videos cancel` · scopes `videos:write`

Stop a queued or processing video (credits released)

Parameters:
- `video_id` (path, string, required): The video id

#### Make a video again

`POST /api/v1/videos/{video_id}/retry` · MCP tool `retry_video` · CLI `kinetune videos retry` · scopes `videos:write`

Reuses the Look it made, with its background media and loops, so nothing already made is paid for again. A video that failed before its Look was saved is designed afresh.

Parameters:
- `video_id` (path, string, required): The video id

#### Delete a video

`DELETE /api/v1/videos/{video_id}` · MCP tool `delete_video` · CLI `kinetune videos delete` · scopes `videos:write`

Delete a finished video and its files

Parameters:
- `video_id` (path, string, required): The video id

### Community

#### Suggest an idea

`POST /api/v1/ideas` · MCP tool `suggest_idea` · CLI `kinetune ideas suggest` · scopes `videos:write`, `music:write`, `library:write`

Posts an idea to the Community board in the app, where everyone signed in can vote and comment, and Kinetune says what is planned and what shipped. Use it when the person asks for something the product can't do yet ("I wish it could…"): say it in their words, one line, with how they would use it in body. It is public to Kinetune's users under the person's name, so leave out private links and contact details, and ask before posting. Suggesting votes for the idea and follows it: the person hears by email when it ships. At most 5 a day.

Parameters:
- `title` (body, string, required): The idea in one line, in the person's words
- `body` (body, string): How they would use it: their release, the platform, why it matters
- `area` (body, "lyric-video" | "canvas" | "music-video" | "everything", default "everything"): What it is about: lyric-video, canvas, music-video, or everything (the whole app)