{"openapi":"3.1.0","info":{"title":"SongUp AI API","version":"1.0.0","description":"SongUp AI is an AI song maker. Make songs with vocals in 76 languages from a prompt or your own lyrics, and get each finished song's audio. Calls use your account's songs, under the same rules as songupai.com.","contact":{"name":"SongUp AI support","email":"support@songupai.com","url":"https://www.songupai.com/developers"},"termsOfService":"https://www.songupai.com/terms"},"servers":[{"url":"https://www.songupai.com/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/me":{"get":{"operationId":"getAccount","summary":"The account behind the API key","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/songs":{"get":{"operationId":"listSongs","summary":"List songs, newest first","description":"With status=completed, songs are ordered by when they finished: use it as a \"song finished\" polling trigger and remember the ids you have seen.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["any","completed","pending","failed"],"default":"any"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"since","in":"query","description":"Only songs created (or, with status=completed, finished) after this ISO 8601 time","schema":{"type":"string"}}],"responses":{"200":{"description":"Songs","content":{"application/json":{"schema":{"type":"object","properties":{"songs":{"type":"array","items":{"$ref":"#/components/schemas/Song"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSong","summary":"Make a song","description":"Starts a song and returns it with status pending. Songs from your own words take about a minute: poll GET /songs/{id} until status is completed or failed. One song at a time per account. A free account with no songs left gets a ready-made song from the SongUp AI library that fits the prompt (catalog_match: true), already completed.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string. A retry with the same key returns the same song instead of making another.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSong"}}}},"responses":{"201":{"description":"Song started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"400":{"description":"Invalid input, or a prompt SongUp AI cannot make","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No songs left (no_songs_left)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Own lyrics need SongUp AI Pro (lyrics_need_pro)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A song for this account is still being made (song_in_progress)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/songs/{id}":{"get":{"operationId":"getSong","summary":"Get a song","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Song","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Song"}}}},"404":{"description":"Not a song in this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/languages":{"get":{"operationId":"listLanguages","summary":"Song languages and music types","security":[],"responses":{"200":{"description":"Languages and music types"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from https://www.songupai.com/settings?tab=developers, starting with sup_"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"no_songs_left"},"message":{"type":"string"}},"required":["code","message"]}}},"Account":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"plan":{"type":"string","example":"pro"},"songs_left":{"type":"integer","description":"Songs that can still be composed from your own words"},"catalog_matches_left":{"type":"integer","description":"Free accounts: ready-made library songs still available"}}},"CreateSong":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":1000,"example":"A happy birthday song for my sister Sara, upbeat pop"},"lyrics":{"type":"string","maxLength":3000,"description":"Your own lyrics (Pro, or a free account's first songs)"},"language":{"type":"string","enum":["English","Hindi","Spanish","French","German","Japanese","Korean","Portuguese","Arabic","Urdu","Turkish","Persian","Indonesian","Malay","Tamil","Punjabi","Bengali","Italian","Russian","Chinese","Vietnamese","Thai","Filipino","Swahili","Marathi","Telugu","Gujarati","Kannada","Malayalam","Nepali","Sinhala","Pashto","Hausa","Yoruba","Amharic","Polish","Dutch","Ukrainian","Romanian","Greek","Hebrew","Burmese","Khmer","Azerbaijani","Uzbek","Kurdish","Czech","Hungarian","Swedish","Norwegian","Danish","Finnish","Serbian","Croatian","Bulgarian","Slovak","Lithuanian","Albanian","Catalan","Kazakh","Georgian","Armenian","Mongolian","Lao","Javanese","Sundanese","Cebuano","Odia","Assamese","Sindhi","Somali","Zulu","Igbo","Afrikaans","Haitian Creole","Tigrinya"],"description":"Leave empty to follow the prompt's language"},"music_type":{"type":"string","enum":["Full Vocal Song","Only Vocals","Nursery Rhymes","Instrumental Beat","Lo-Fi Beats","Cinematic Score","Brand Intro","Short Jingle"],"default":"Full Vocal Song"},"style":{"type":"string","maxLength":60,"example":"Pop"},"title":{"type":"string","maxLength":100}}},"Song":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["pending","completed","failed"]},"audio_url":{"type":["string","null"],"description":"MP3 link once completed"},"song_url":{"type":"string","description":"The song's page on songupai.com (private songs open for their owner)"},"language":{"type":["string","null"]},"music_type":{"type":["string","null"]},"style":{"type":["string","null"]},"lyrics":{"type":["string","null"]},"duration_seconds":{"type":["number","null"]},"catalog_match":{"type":"boolean","description":"A ready-made song from the SongUp AI library, not composed from your words"},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}}