add_artist_photos
ChatGPTUpload one or more photos of the artist (JPEG, PNG or WebP). Up 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. Each is kept upright at up to 1536 px, with a small thumbnail; the uploaded file itself is not kept.
archive_artist
ChatGPTRemove an artist that has no songs. Refused (409) while the artist still has songs.
archive_song
ChatGPTRemove a song (its videos stay)
cancel_video
ChatGPTStop a queued or processing video (credits released)
clear_song_lyrics
ChatGPTGo back to the transcribed words. Videos made from then on show the words as transcribed.
create_artist
ChatGPTAdd an artist by name. Names are unique per organization (409 when taken).
create_canvas
ChatGPTMake the Canvas a quote priced (spends credits). 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.
create_lyric_video
ChatGPTMake the lyric video a quote priced (spends credits). 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.
create_organization
ChatGPTA new organization owned by you, with its own music, videos, Looks and credits. Creates an empty organization with the signed-in person as its owner; with an API key, the member who created the key (the key needs organizations:write). It starts with no credits. 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.
create_song
ChatGPTAdd a song: master audio and square cover art. 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.
delete_artist_photo
ChatGPTRemove one photo
delete_kit_piece
ChatGPTRemove an outfit, place or prop A plan that used it can’t be made any more: plan again.
delete_look
ChatGPTRemove one of your Looks (videos made with it stay)
delete_video
ChatGPTDelete a finished video and its files
get_account
ChatGPTWho you are signed in as, the organization and its credit balance. Returns the organization the credentials act for, how they authenticate and their scopes, the credit balance (available, monthly, top-ups) and its plan, if any (where it is billed, when the period ends, and a downgrade or interval switch waiting for the renewal as scheduled_change). Check it before creating videos.
get_artist
ChatGPTOne artist
get_kit_piece
ChatGPTOne outfit, place or prop
get_look
ChatGPTOne Look with its design and preview images. 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).
get_music_video_lookbook
ChatGPTA lookbook with its pictures as they are drawn 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).
get_music_video_plan
ChatGPTA plan made earlier
get_options
ChatGPTVideo types, Look categories, background sources, formats and the current credit prices. Everything a request can choose from, with the credit table. Use it to pick a category or source and to explain prices.
get_song
ChatGPTOne song and its analysis status. 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).
get_song_analysis
ChatGPTWord-timed lyrics, tempo, beats, sections and hook. Use the section times to choose a trim for a lyric video. 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).
get_video
ChatGPTStatus, progress, credits and, when completed, the download links. status 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. 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. 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.
keep_music_video_lookbook_piece
ChatGPTWhether a piece goes into the video
list_artist_photos
ChatGPTThe artist’s photos (identity references, up to 6). 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.
list_artists
ChatGPTArtists by name, with their song and photo counts and a picture. 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.
list_kit
ChatGPTOutfits, places and props a music video brief can mention 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.
list_looks
ChatGPTBrowse Official, Community and your own Looks. 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.
list_organizations
ChatGPTThe organizations you belong to, your role in each and the one these credentials act for. Every organization the signed-in person is a member of; with an API key, the member who created it (the key needs organizations:read). current marks the organization these credentials act for. Each organization has its own 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.
list_songs
ChatGPTSongs with their cover, duration and analysis status. 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.
list_videos
ChatGPTVideos, newest first, with status and thumbnails. Each video's outputs carry aspect_ratio, poster_url, poster_seconds and web_url (for thumbnails and previews); get_video has the download links.
plan_music_video
ChatGPTThe director's shot list for a music video, the idea and every shot, before anything is charged 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.
quote_canvas
ChatGPTThe exact credits for a Spotify Canvas, before anything is charged. 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.
quote_lyric_video
ChatGPTThe exact credits for a lyric video, before anything is charged. 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.
quote_music_video
ChatGPTThe exact credits for an AI music video, before anything is charged 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.
reanalyze_song
ChatGPTRetry a failed analysis
rename_artist
ChatGPTChange an artist’s name
rename_look
ChatGPTRename one of your Looks
rename_song
ChatGPTChange a song’s title
render_music_video_lookbook
ChatGPTDraws the pieces not drawn yet (spends credits) 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.
retry_video
ChatGPTRun a finished, failed or cancelled video again (new charge). 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.
search_stock
ChatGPTFind stock photos or clips to use as a background. 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.
set_artist_picture
ChatGPTChoose which photo is the artist’s picture, and how it is cropped to a square. 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.
set_look_visibility
ChatGPTMake one of your Looks public (earns 10 credits) or private. Public Looks join the Community library under your @username. A Look that shows your artist stays private (409).
set_song_lyrics
ChatGPTGive a song its own lyrics, or replace them. 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.
show_looks
ChatGPTShows Looks to the person as a gallery they can play and pick from (each Look plays as the real render). Use it whenever they want to see, browse or choose Looks; pass song_id to preview the Looks with one of their analyzed songs. Their pick comes back as a message naming the Look.
show_songs
ChatGPTShows the person's songs as a list with covers, length and analysis status, each offering a lyric video or a Canvas. Use it when they want to see or pick a song.
show_video
ChatGPTShows videos as players: the card follows a render on its own (progress while it renders), then plays the finished video with a download per format. Call it right after create_lyric_video or create_canvas with the video ids it returned (no need to wait_for_video then), or whenever the person asks to see a video.
swap_music_video_place
ChatGPTAnother stock photo for one of a plan's places 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.
update_kit_piece
ChatGPTRename it, change its handle or description, or crop it again crop is cut again from the image the piece was added from. Plans already made keep the pieces as they were planned.
update_music_video_lookbook
ChatGPTWhether its kept pieces join the kit when a video is planned from it 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.
update_organization
ChatGPTRename the organization (workspace) these credentials act for, or switch it between artist and label 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).
upload_background
ChatGPTUpload your own photo or video to design a New Look around. 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"}.
wait_for_video
ChatGPTWaits up to max_seconds (default 50) for a video to finish, then returns it like get_video. Call again while status is queued or processing.
