{"openapi":"3.1.0","info":{"title":"Kinetune API","version":"1","description":"Lyric videos and Spotify Canvas loops from your songs. The same operations power the app, the MCP server, the CLI and the n8n node."},"servers":[{"url":"https://kinetune.com"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An organization API key (kt_live_…) or an OAuth access token"},"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://kinetune.com/api/auth/oauth2/authorize","tokenUrl":"https://kinetune.com/api/auth/oauth2/token","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"}}}}}},"paths":{"/api/v1/account":{"get":{"operationId":"account.get","summary":"Get the account","description":"Who you are signed in as, the organization and its credit balance\n\nReturns the organization the credentials act for, how they authenticate and their scopes, and the credit balance (available, monthly, top-ups). Check it before creating videos.","tags":["account"],"parameters":[],"security":[{"bearer":[]},{"oauth2":["videos:read","music:read","library:read"]}],"x-operations":[{"id":"account.get","mcpTool":"get_account","cli":"kinetune account"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/options":{"get":{"operationId":"options.get","summary":"List the options","description":"Video types, Look categories, background sources, formats and the current credit prices\n\nEverything a request can choose from, with the credit table. Use it to pick a category or source and to explain prices.","tags":["account"],"parameters":[],"security":[{"bearer":[]},{"oauth2":["videos:read","music:read","library:read"]}],"x-operations":[{"id":"options.get","mcpTool":"get_options","cli":"kinetune options"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/artists":{"get":{"operationId":"artists.list","summary":"List artists","description":"Every artist with their song and photo counts\n\nSongs belong to an artist; create the artist first.","tags":["artists"],"parameters":[],"security":[{"bearer":[]},{"oauth2":["music:read","videos:read"]}],"x-operations":[{"id":"artists.list","mcpTool":"list_artists","cli":"kinetune artists list"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"post":{"operationId":"artists.create","summary":"Create an artist","description":"Add an artist by name\n\nNames are unique per organization (409 when taken).","tags":["artists"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Create an artist","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The artist name"}},"required":["name"]}}}},"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"artists.create","mcpTool":"create_artist","cli":"kinetune artists create"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/artists/{artist_id}":{"get":{"operationId":"artists.get","summary":"Get an artist","description":"One artist","tags":["artists"],"parameters":[{"name":"artist_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The artist id"},"description":"The artist id"}],"security":[{"bearer":[]},{"oauth2":["music:read","videos:read"]}],"x-operations":[{"id":"artists.get","mcpTool":"get_artist","cli":"kinetune artists get"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"patch":{"operationId":"artists.update","summary":"Rename an artist","description":"Change an artist’s name","tags":["artists"],"parameters":[{"name":"artist_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The artist id"},"description":"The artist id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Rename an artist","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"The new name"}},"required":["name"]}}}},"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"artists.update","mcpTool":"rename_artist","cli":"kinetune artists rename"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"delete":{"operationId":"artists.archive","summary":"Archive an artist","description":"Remove an artist that has no songs\n\nRefused (409) while the artist still has songs.","tags":["artists"],"parameters":[{"name":"artist_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The artist id"},"description":"The artist id"}],"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"artists.archive","mcpTool":"archive_artist","cli":"kinetune artists archive"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/artists/{artist_id}/photos":{"get":{"operationId":"artist_photos.list","summary":"List artist photos","description":"The artist’s photos (identity references, up to 6)\n\nPhotos keep the artist recognizable when a Look or Canvas shows them; the cover art stays the creative source.","tags":["artists"],"parameters":[{"name":"artist_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The artist id"},"description":"The artist id"}],"security":[{"bearer":[]},{"oauth2":["music:read","videos:read"]}],"x-operations":[{"id":"artist_photos.list","mcpTool":"list_artist_photos","cli":"kinetune artists photos list"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"post":{"operationId":"artist_photos.add","summary":"Add artist photos","description":"Upload one or more photos of the artist (JPEG, PNG or WebP)\n\nUp to 6 per artist, at least 512 px on the short side, up to 15 MB each. Only with the rights to use them (rights_confirmed). They are identity references only: never shown publicly or used as they are.","tags":["artists"],"parameters":[{"name":"artist_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The artist id"},"description":"The artist id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Add artist photos","properties":{"photo_urls":{"description":"Public https URLs of the photos (or upload files with the CLI)","minItems":1,"maxItems":6,"type":"array","items":{"type":"string","maxLength":2000,"format":"uri","description":"A public https URL of a photo"}},"rights_confirmed":{"type":"boolean","const":true,"description":"You have the rights to use these photos of the artist"}},"required":["rights_confirmed"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"photos":{"type":"array","items":{"type":"string","format":"binary"}}}}}}},"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"artist_photos.add","mcpTool":"add_artist_photos","cli":"kinetune artists photos add"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/artists/{artist_id}/photos/{photo_id}":{"delete":{"operationId":"artist_photos.delete","summary":"Delete an artist photo","description":"Remove one photo","tags":["artists"],"parameters":[{"name":"artist_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The artist id"},"description":"The artist id"},{"name":"photo_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The photo id"},"description":"The photo id"}],"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"artist_photos.delete","mcpTool":"delete_artist_photo","cli":"kinetune artists photos delete"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/songs":{"get":{"operationId":"songs.list","summary":"List songs","description":"Songs with their cover, duration and analysis status\n\nA song must be analyzed (analysis.status \"ready\") before videos can be made.","tags":["songs"],"parameters":[{"name":"artist_id","in":"query","required":false,"schema":{"description":"Only this artist’s songs","type":"string","minLength":1,"maxLength":120},"description":"Only this artist’s songs"}],"security":[{"bearer":[]},{"oauth2":["music:read","videos:read"]}],"x-operations":[{"id":"songs.list","mcpTool":"list_songs","cli":"kinetune songs list"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"post":{"operationId":"songs.create","summary":"Upload a song","description":"Add a song: master audio and square cover art\n\nAudio: MP3, WAV or M4A up to 250 MB. Cover: a square JPEG or PNG, 1000–6000 px (3000×3000 recommended), up to 20 MB. The song is analyzed next (lyrics, beats, sections): poll get_song until analysis.status is \"ready\", usually about a minute.","tags":["songs"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Upload a song","properties":{"artist_id":{"type":"string","minLength":1,"maxLength":120,"description":"The artist id"},"title":{"type":"string","minLength":1,"maxLength":300,"description":"The song title"},"language":{"description":"Lyrics language (ISO 639-1, e.g. \"en\"); detected when omitted","type":"string","pattern":"^[a-z]{2,3}$"},"audio_url":{"type":"string","maxLength":2000,"format":"uri","description":"A public https URL of the master audio"},"cover_art_url":{"type":"string","maxLength":2000,"format":"uri","description":"A public https URL of the square cover art"}},"required":["artist_id","title"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"audio":{"type":"string","format":"binary"},"cover_art":{"type":"string","format":"binary"}}}}}},"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"songs.create","mcpTool":"create_song","cli":"kinetune songs create"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/songs/{song_id}":{"get":{"operationId":"songs.get","summary":"Get a song","description":"One song and its analysis status","tags":["songs"],"parameters":[{"name":"song_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"description":"The song id"}],"security":[{"bearer":[]},{"oauth2":["music:read","videos:read"]}],"x-operations":[{"id":"songs.get","mcpTool":"get_song","cli":"kinetune songs get"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"patch":{"operationId":"songs.update","summary":"Rename a song","description":"Change a song’s title","tags":["songs"],"parameters":[{"name":"song_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"description":"The song id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Rename a song","properties":{"title":{"type":"string","minLength":1,"maxLength":300,"description":"The new title"}},"required":["title"]}}}},"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"songs.update","mcpTool":"rename_song","cli":"kinetune songs rename"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"delete":{"operationId":"songs.archive","summary":"Archive a song","description":"Remove a song (its videos stay)","tags":["songs"],"parameters":[{"name":"song_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"description":"The song id"}],"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"songs.archive","mcpTool":"archive_song","cli":"kinetune songs archive"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/songs/{song_id}/analysis":{"get":{"operationId":"songs.analysis","summary":"Get a song’s analysis","description":"Word-timed lyrics, tempo, beats, sections and hook\n\nUse the section times to choose a trim for a lyric video.","tags":["songs"],"parameters":[{"name":"song_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"description":"The song id"}],"security":[{"bearer":[]},{"oauth2":["music:read","videos:read"]}],"x-operations":[{"id":"songs.analysis","mcpTool":"get_song_analysis","cli":"kinetune songs analysis"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"post":{"operationId":"songs.reanalyze","summary":"Analyze a song again","description":"Retry a failed analysis","tags":["songs"],"parameters":[{"name":"song_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"description":"The song id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Analyze a song again","properties":{},"required":[]}}}},"security":[{"bearer":[]},{"oauth2":["music:write","videos:write"]}],"x-operations":[{"id":"songs.reanalyze","mcpTool":"reanalyze_song","cli":"kinetune songs reanalyze"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/looks":{"get":{"operationId":"looks.list","summary":"List Looks","description":"Browse Official, Community and your own Looks\n\nA Look is a complete, reusable lyric-video design. Pass its id as {\"mode\":\"existing\",\"id\":…} to reuse it exactly.","tags":["looks"],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"description":"Which library; default all","type":"string","enum":["all","official","community","mine"]},"description":"Which library; default all"},{"name":"category","in":"query","required":false,"schema":{"description":"A category id from get_options","type":"string","maxLength":40},"description":"A category id from get_options"},{"name":"q","in":"query","required":false,"schema":{"description":"Search words","type":"string","maxLength":100},"description":"Search words"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["newest","popular"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}],"security":[{"bearer":[]},{"oauth2":["library:read","videos:read"]}],"x-operations":[{"id":"looks.list","mcpTool":"list_looks","cli":"kinetune looks list"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/looks/{look_id}":{"get":{"operationId":"looks.get","summary":"Get a Look","description":"One Look with its design and preview images","tags":["looks"],"parameters":[{"name":"look_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The Look id"},"description":"The Look id"}],"security":[{"bearer":[]},{"oauth2":["library:read","videos:read"]}],"x-operations":[{"id":"looks.get","mcpTool":"get_look","cli":"kinetune looks get"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"patch":{"operationId":"looks.rename","summary":"Rename a Look","description":"Rename one of your Looks","tags":["looks"],"parameters":[{"name":"look_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The Look id"},"description":"The Look id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Rename a Look","properties":{"name":{"type":"string","minLength":2,"maxLength":60,"description":"The new name"}},"required":["name"]}}}},"security":[{"bearer":[]},{"oauth2":["library:write","videos:write"]}],"x-operations":[{"id":"looks.rename","mcpTool":"rename_look","cli":"kinetune looks rename"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"delete":{"operationId":"looks.delete","summary":"Delete a Look","description":"Remove one of your Looks (videos made with it stay)","tags":["looks"],"parameters":[{"name":"look_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The Look id"},"description":"The Look id"}],"security":[{"bearer":[]},{"oauth2":["library:write","videos:write"]}],"x-operations":[{"id":"looks.delete","mcpTool":"delete_look","cli":"kinetune looks delete"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/looks/{look_id}/visibility":{"post":{"operationId":"looks.visibility","summary":"Publish or unpublish a Look","description":"Make one of your Looks public (earns 10 credits) or private\n\nPublic Looks join the Community library under your @username. A Look that shows your artist stays private (409).","tags":["looks"],"parameters":[{"name":"look_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The Look id"},"description":"The Look id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Publish or unpublish a Look","properties":{"visibility":{"type":"string","enum":["public","private"]}},"required":["visibility"]}}}},"security":[{"bearer":[]},{"oauth2":["library:write","videos:write"]}],"x-operations":[{"id":"looks.visibility","mcpTool":"set_look_visibility","cli":"kinetune looks visibility"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/quotes":{"post":{"operationId":"quotes.create","summary":"Quote a lyric video or Quote a Canvas","description":"The exact credits for a lyric video, before anything is charged\n\nReturns 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.\n\nThe exact credits for a Spotify Canvas, before anything is charged\n\nReturns 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.","tags":["videos"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Quote a lyric video","properties":{"type":{"const":"lyric-video"},"song_id":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"variations":{"default":1,"description":"1–4 different New Looks, one video each (an Existing Look renders one)","type":"integer","minimum":1,"maximum":4},"callback_url":{"description":"An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value","type":"string","maxLength":2000},"metadata":{"description":"Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"look":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"new"},"category":{"type":"string","enum":["release","fall","halloween","christmas","summer","valentines","mood","retro","synthwave","street","nature","luxury","abstract","minimal","neon","pop-art"]},"background":{"default":{"quality":"high"},"type":"object","properties":{"source":{"type":"string","enum":["ai-image","ai-video","stock-photo","stock-video","designed"]},"quality":{"default":"high","type":"string","enum":["standard","high","ultra"]}},"additionalProperties":false},"visibility":{"default":"private","type":"string","enum":["private","public"]},"direction":{"type":"string","maxLength":2000},"feature_artist":{"default":"auto","type":"string","enum":["auto","always","never"]}},"required":["mode","category"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"existing"},"id":{"type":"string","minLength":1,"maxLength":120}},"required":["mode","id"],"additionalProperties":false}],"description":"{\"mode\":\"existing\",\"id\":\"look_…\"} to reuse a saved Look, or {\"mode\":\"new\",\"category\":\"…\",\"background\":{\"source\":\"ai-image\",\"quality\":\"high\"},\"visibility\":\"private\",\"direction\":\"…\",\"feature_artist\":\"auto\"} to have one designed"},"aspect_ratios":{"default":["9:16"],"description":"Formats to render, each its own file: \"9:16\" (vertical), \"16:9\" (wide), \"1:1\" (square)","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["9:16","16:9","1:1"]}},"display":{"default":{"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true},"description":"Which elements show (title, artist, cover, lyrics, badges, headline) and their sizes","type":"object","properties":{"title":{"default":true,"type":"boolean"},"artist":{"default":true,"type":"boolean"},"cover":{"default":true,"type":"boolean"},"lyrics":{"default":true,"type":"boolean"},"badges":{"default":true,"type":"boolean"},"headline":{"type":"string","enum":["none","new-release","out-now","coming-soon","listen-now"]},"cover_scale":{"type":"number","minimum":0.75,"maximum":1.25},"text_scale":{"type":"number","minimum":0.85,"maximum":1.3},"artist_scale":{"type":"number","minimum":0.85,"maximum":1.5},"spacing_scale":{"type":"number","minimum":0.75,"maximum":1.5}},"additionalProperties":false},"trim":{"description":"Render only this section of the song (at least 8 seconds)","type":"object","properties":{"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","exclusiveMinimum":0}},"required":["start_seconds","end_seconds"],"additionalProperties":false}},"required":["type","song_id","look"]},{"type":"object","title":"Quote a Canvas","properties":{"type":{"const":"canvas"},"song_id":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"variations":{"default":1,"description":"1–4 different Canvases","type":"integer","minimum":1,"maximum":4},"callback_url":{"description":"An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value","type":"string","maxLength":2000},"metadata":{"description":"Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"source":{"default":"ai-video","description":"ai-video (default), ai-image, stock-photo or stock-video","type":"string","enum":["ai-video","ai-image","stock-photo","stock-video"]},"quality":{"default":"standard","description":"AI video model tier: standard or high","type":"string","enum":["standard","high"]},"resolution":{"default":"1080p","description":"1080p (1080×1920) or 720p","type":"string","enum":["720p","1080p"]},"style":{"description":"Optional visual style","type":"string","enum":["cinematic","dreamy","abstract","surreal","retro","minimal","dark","vibrant","nature","urban"]},"direction":{"description":"Optional mood, motifs or references; the concept still comes from the cover","type":"string","maxLength":2000},"feature_artist":{"default":"auto","description":"Whether the Canvas shows the artist (AI sources; needs artist photos for \"always\")","type":"string","enum":["auto","always","never"]},"seconds":{"default":8,"description":"Canvas length in whole seconds, 5–8 (default 8). Spotify loops it, so no part of the song is chosen","type":"integer","minimum":5,"maximum":8}},"required":["type","song_id"]}]}}}},"security":[{"bearer":[]},{"oauth2":["videos:write","videos:read"]}],"x-operations":[{"id":"quotes.lyric_video","mcpTool":"quote_lyric_video","cli":"kinetune quote lyric-video"},{"id":"quotes.canvas","mcpTool":"quote_canvas","cli":"kinetune quote canvas"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/videos":{"post":{"operationId":"videos.create","summary":"Create a lyric video or Create a Canvas","description":"Make the lyric video a quote priced (spends credits)\n\nSend 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.\n\nMake the Canvas a quote priced (spends credits)\n\nSend 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.","tags":["videos"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Create a lyric video","properties":{"type":{"const":"lyric-video"},"song_id":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"variations":{"default":1,"description":"1–4 different New Looks, one video each (an Existing Look renders one)","type":"integer","minimum":1,"maximum":4},"callback_url":{"description":"An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value","type":"string","maxLength":2000},"metadata":{"description":"Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"look":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"new"},"category":{"type":"string","enum":["release","fall","halloween","christmas","summer","valentines","mood","retro","synthwave","street","nature","luxury","abstract","minimal","neon","pop-art"]},"background":{"default":{"quality":"high"},"type":"object","properties":{"source":{"type":"string","enum":["ai-image","ai-video","stock-photo","stock-video","designed"]},"quality":{"default":"high","type":"string","enum":["standard","high","ultra"]}},"additionalProperties":false},"visibility":{"default":"private","type":"string","enum":["private","public"]},"direction":{"type":"string","maxLength":2000},"feature_artist":{"default":"auto","type":"string","enum":["auto","always","never"]}},"required":["mode","category"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"existing"},"id":{"type":"string","minLength":1,"maxLength":120}},"required":["mode","id"],"additionalProperties":false}],"description":"{\"mode\":\"existing\",\"id\":\"look_…\"} to reuse a saved Look, or {\"mode\":\"new\",\"category\":\"…\",\"background\":{\"source\":\"ai-image\",\"quality\":\"high\"},\"visibility\":\"private\",\"direction\":\"…\",\"feature_artist\":\"auto\"} to have one designed"},"aspect_ratios":{"default":["9:16"],"description":"Formats to render, each its own file: \"9:16\" (vertical), \"16:9\" (wide), \"1:1\" (square)","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["9:16","16:9","1:1"]}},"display":{"default":{"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true},"description":"Which elements show (title, artist, cover, lyrics, badges, headline) and their sizes","type":"object","properties":{"title":{"default":true,"type":"boolean"},"artist":{"default":true,"type":"boolean"},"cover":{"default":true,"type":"boolean"},"lyrics":{"default":true,"type":"boolean"},"badges":{"default":true,"type":"boolean"},"headline":{"type":"string","enum":["none","new-release","out-now","coming-soon","listen-now"]},"cover_scale":{"type":"number","minimum":0.75,"maximum":1.25},"text_scale":{"type":"number","minimum":0.85,"maximum":1.3},"artist_scale":{"type":"number","minimum":0.85,"maximum":1.5},"spacing_scale":{"type":"number","minimum":0.75,"maximum":1.5}},"additionalProperties":false},"trim":{"description":"Render only this section of the song (at least 8 seconds)","type":"object","properties":{"start_seconds":{"type":"number","minimum":0},"end_seconds":{"type":"number","exclusiveMinimum":0}},"required":["start_seconds","end_seconds"],"additionalProperties":false},"quote_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The quote_id from the matching quote: the request must be identical"}},"required":["type","song_id","look","quote_id"]},{"type":"object","title":"Create a Canvas","properties":{"type":{"const":"canvas"},"song_id":{"type":"string","minLength":1,"maxLength":120,"description":"The song id"},"variations":{"default":1,"description":"1–4 different Canvases","type":"integer","minimum":1,"maximum":4},"callback_url":{"description":"An https URL to POST the finished video to (signed; see Callbacks). Quote and create with the same value","type":"string","maxLength":2000},"metadata":{"description":"Your own JSON (an order id, for example): kept with the video and returned in its request. Quote and create with the same value","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"source":{"default":"ai-video","description":"ai-video (default), ai-image, stock-photo or stock-video","type":"string","enum":["ai-video","ai-image","stock-photo","stock-video"]},"quality":{"default":"standard","description":"AI video model tier: standard or high","type":"string","enum":["standard","high"]},"resolution":{"default":"1080p","description":"1080p (1080×1920) or 720p","type":"string","enum":["720p","1080p"]},"style":{"description":"Optional visual style","type":"string","enum":["cinematic","dreamy","abstract","surreal","retro","minimal","dark","vibrant","nature","urban"]},"direction":{"description":"Optional mood, motifs or references; the concept still comes from the cover","type":"string","maxLength":2000},"feature_artist":{"default":"auto","description":"Whether the Canvas shows the artist (AI sources; needs artist photos for \"always\")","type":"string","enum":["auto","always","never"]},"seconds":{"default":8,"description":"Canvas length in whole seconds, 5–8 (default 8). Spotify loops it, so no part of the song is chosen","type":"integer","minimum":5,"maximum":8},"quote_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The quote_id from the matching quote: the request must be identical"}},"required":["type","song_id","quote_id"]}]}}}},"security":[{"bearer":[]},{"oauth2":["videos:write"]}],"x-operations":[{"id":"videos.create_lyric_video","mcpTool":"create_lyric_video","cli":"kinetune create lyric-video"},{"id":"videos.create_canvas","mcpTool":"create_canvas","cli":"kinetune create canvas"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"get":{"operationId":"videos.list","summary":"List videos","description":"Videos, newest first, with status and thumbnails","tags":["videos"],"parameters":[{"name":"song_id","in":"query","required":false,"schema":{"description":"Only this song’s videos","type":"string","minLength":1,"maxLength":120},"description":"Only this song’s videos"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["lyric-video","canvas"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"security":[{"bearer":[]},{"oauth2":["videos:read"]}],"x-operations":[{"id":"videos.list","mcpTool":"list_videos","cli":"kinetune videos list"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/videos/{video_id}":{"get":{"operationId":"videos.get","summary":"Get a video","description":"Status, progress, credits and, when completed, the download links\n\nstatus is queued, processing, completed, failed or cancelled. Completed videos have outputs with download_url (full quality), web_url (720p) and poster_url, signed for 7 days.","tags":["videos"],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The video id"},"description":"The video id"}],"security":[{"bearer":[]},{"oauth2":["videos:read"]}],"x-operations":[{"id":"videos.get","mcpTool":"get_video","cli":"kinetune videos get"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}},"delete":{"operationId":"videos.delete","summary":"Delete a video","description":"Delete a finished video and its files","tags":["videos"],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The video id"},"description":"The video id"}],"security":[{"bearer":[]},{"oauth2":["videos:write"]}],"x-operations":[{"id":"videos.delete","mcpTool":"delete_video","cli":"kinetune videos delete"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/videos/{video_id}/cancel":{"post":{"operationId":"videos.cancel","summary":"Cancel a video","description":"Stop a queued or processing video (credits released)","tags":["videos"],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The video id"},"description":"The video id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Cancel a video","properties":{},"required":[]}}}},"security":[{"bearer":[]},{"oauth2":["videos:write"]}],"x-operations":[{"id":"videos.cancel","mcpTool":"cancel_video","cli":"kinetune videos cancel"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}},"/api/v1/videos/{video_id}/retry":{"post":{"operationId":"videos.retry","summary":"Make a video again","description":"Run a finished, failed or cancelled video again (new charge)\n\nReuses its Look, background media and loops, so nothing already made is paid for again.","tags":["videos"],"parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"description":"The video id"},"description":"The video id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","title":"Make a video again","properties":{},"required":[]}}}},"security":[{"bearer":[]},{"oauth2":["videos:write"]}],"x-operations":[{"id":"videos.retry","mcpTool":"retry_video","cli":"kinetune videos retry"}],"responses":{"200":{"description":"OK"},"201":{"description":"Created"},"400":{"description":"Invalid request"},"401":{"description":"Missing or invalid credentials"},"402":{"description":"Not enough credits"},"403":{"description":"Missing scope"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"422":{"description":"Unprocessable"}}}}}}