POST HTTPS://API.VOICEMAGIX.COM/AUTH/TOKEN
REQUEST BODY DATA (JSON) |
VALUE TYPE |
VALUE |
username |
Required. string |
- |
password |
Required. string |
- |
Generates an authentication token for given credentials. On success it returns the user information and the generated token together with a 200 OK HTTP status code in the response header. Using the given token one has to add to all following three methods a header key Authorization with value ‘Bearer <token>‘
NOTE: write down your token, because it is generated only once!
NOTE: write down your token, because it is generated only once!
An example request:
curl --request POST --url https://api.voicemagix.com/auth/token --form username=testuser --form password=testpassword
POST HTTPS://API.VOICEMAGIX.COM/ALIGNMENTS
REQUEST BODY DATA (JSON) |
VALUE TYPE |
VALUE |
lyrics_text |
Lyrics as string. Separate lyrics lines by \n character. |
Example: “line lyrics one\nline lyrics two” |
lyrics_file |
Lyrics text file as attachment where each lyrics line is on a new line. |
- |
composition_id |
integer |
- |
accompaniment |
Required. integer |
{1,2} 1=acapella, 2=multi-instrumental |
level |
integer |
{1,2}, 1=words, 2=lines. default= 1 |
title |
string. The title of the composition |
if not given will be blank in the alignment result |
end_times |
integer |
{1,2} 1=no, 2=yes. default= 1 |
Creates an alignment request. On success, the response body contains an alignment_id and composition_id in JSON format and the HTTP status code in the response header is 201 Created. The alignment_id is used to identify future audio upload and result requests. The composition_id is used in future alignment requests for a recording with same lyrics, e.g. that is the same composition.
Lyrics could be given as either string or as a text file. If lyrics are given as text file, the post type should be ‘multipart/form-data’, otherwise ‘application/json’ is recommended. Meaningful lyrics lines are encouraged as they could help increase the alignment accuracy. One of lyrics_text, lyrics_file or composition_id has to be given.
Accompaniment defines if the algorithm will try to discard instruments accompanying the singing voice. Level defines the level on which result timestamps will be produced - for each word or for each line.
The end_times option toggles if end timestamp for each line/word will be output. Usually end line times make sense when having longer non-vocal intervals between the lines.
Lyrics could be given as either string or as a text file. If lyrics are given as text file, the post type should be ‘multipart/form-data’, otherwise ‘application/json’ is recommended. Meaningful lyrics lines are encouraged as they could help increase the alignment accuracy. One of lyrics_text, lyrics_file or composition_id has to be given.
Accompaniment defines if the algorithm will try to discard instruments accompanying the singing voice. Level defines the level on which result timestamps will be produced - for each word or for each line.
The end_times option toggles if end timestamp for each line/word will be output. Usually end line times make sense when having longer non-vocal intervals between the lines.
An example request: curl --request POST --url https://api.voicemagix.com/alignments/ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MjcyNzExODYsInVzZXJuYW1lIjoidGVzdHVzZXIifQ.k-kZb7iRevbDKRMm1sO-uu1snUTfsODIOhO862RI3AE' --header 'Content-Type: multipart/form-data' --form lyrics=@/workspace/test/example/umbrella_line.txt --form accompaniment=1 --form level=2’
An example of calling the method in postman can be found here
POST HTTPS://API.VOICEMAGIX.COM/ALIGNMENTS/UPLOAD
recording_URL |
Required. string |
- |
alignment_id |
Required. integer |
- |
Uploads the audio recording for an already requested alignment. On success, the response body contains the message “Audio uploaded successfully!” in JSON format and the HTTP status code in the response header is 201 Created. Supported formats are .mp3, .mp4, .m4a, .wav, .ogg. If alignment_id does not exist, returns error code 404. Please avoid uploading long files in .wav format because the upload could fail with http timeout due to their big size.
On upload the actual alignment is started and the status of the alignment object is updated to 2=ON_QUEUE. Needs authentication.
On upload the actual alignment is started and the status of the alignment object is updated to 2=ON_QUEUE. Needs authentication.
An example request:
curl --request POST https://api.voicemagix.com/alignments/upload -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MjcyNzExODYsInVzZXJuYW1lIjoidGVzdHVzZXIifQ.k-kZb7iRevbDKRMm1sO-uu1snUTfsODIOhO862RI3AE' -H 'content-type: application/json' -F recording_url=http://127.0.0.1:8000/media/recordings/umbrella_line.mp3 -F alignment_id=2
GET HTTPS://API.VOICEMAGIX.COM/ALIGNMENTS/<alignment_id>
Once the alignment status is ON_QUEUE (e.g. an audio recording has been uploaded), you need to wait (around 50 seconds for a track of 5 minutes) to finish the alignment.
On success, the response body is a JSON object with list of uploaded token timestamps (word timestamps or line timestamps) and the HTTP status code in the response header is 200 OK. if alignment_ID does not exist, return error code 404. When alignment is finished, if successful, the alignment status is 3=DONE, and timestamps have been added. If the status is 2=ON_QUEUE, this means that alignment is still in progress, so please try again later. Status 4=FAILED means that there the alignment is over but failed for the reason given in the field error_reason. Needs authentication.
On success, the response body is a JSON object with list of uploaded token timestamps (word timestamps or line timestamps) and the HTTP status code in the response header is 200 OK. if alignment_ID does not exist, return error code 404. When alignment is finished, if successful, the alignment status is 3=DONE, and timestamps have been added. If the status is 2=ON_QUEUE, this means that alignment is still in progress, so please try again later. Status 4=FAILED means that there the alignment is over but failed for the reason given in the field error_reason. Needs authentication.
An example request: curl --request GET --url https://api.voicemagix.com/alignments/1 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjU0MDYwNjIsInVzZXJuYW1lIjoibWljaGFsIn0.FRDpwMCbAOFZDBOMyMb--25Qy1DdYSVbGznjec6Gydc'
