Skip to main content

Examples of API usage

Scripted Requests​

Here are some examples to the usage of the scripted APIs

Score_audio endpoint​

This demo will be on the command line using a linux-compatible system via the cUrl command.

cURL command using audio_path parameter​

In this example we will use the sentence “When the sunlight strikes raindrops in the air, they act like a prism and form a rainbow.” with the audio available at this public URL https://elsa-api-docs.s3-eu-west-1.amazonaws.com/api_samples/rainbow.wav

curl -XPOST -s https://api.elsanow.io/api/v2/score_audio -F "api_plan=premium" -F "audio_path=https://elsa-api-docs.s3-eu-west-1.amazonaws.com/api_samples/rainbow.wav" -F sentence="When the sunlight strikes raindrops in the air, they act like a prism and form a rainbow" --header "Authorization: ELSA <API_token>"

cURL command using audio_file parameter​

curl -XPOST -s https://api.elsanow.io/api/v2/score_audio -F "api_plan=premium" -F "audio_file=@<path_to_the_file>/rainbow.wav" -F sentence="When the sunlight strikes raindrops in the air, they act like a prism and form a rainbow" --header "Authorization: ELSA <API_token>"

You can change the "api_plan" parameter to obtain more or less detailed results.

Example of Multiple-choice support​

Using the same endpoint and parameters as above, we can also score multiple-choice exercises, where the ELSA engine will: 1) select the word/sentence that most appropriately matches the user’s input; b) score that sentence as in the single-sentence case. To perform multiple-choice, we will send a list of possible sentences in the sentence field:

sentence: [“sentence 0”, “sentence 1”]

There is no limit to the number of sentences you can send.

Here is a way to send the list in a curl command:

sentence="[\"sentence 0\",\"sentence 1\"]"

Unscripted Requests​

Here are some examples of the usage of the unscripted APIs.

Score_audio_plus endpoint​

To implement the calls to ELSA API we can use the “curl” command in any linux-compatible command line.

cURL command using audio_file parameter​

The following sample will return the link to download the result json when called using a local audio file (do not forget the “@” before the path).

curl -XPOST -s https://api.elsanow.io/api/v1/score_audio_plus -F "api_plan=premium" -F "audio_file=@<path_to_your_file.wav>" --header "Authorization: ELSA <API_token>"

If you prefer to receive the json itself as an answer to the call do:

 curl -XPOST -s https://api.elsanow.io/api/v1/score_audio_plus -F "api_plan=premium" -F "return_json=true" -F "audio_file=@<path_to_your_file.wav>" --header "Authorization: ELSA <API_token>"

ASR endpoint​

Example usage of the ASR transcript and word-level time alignment:

curl -XPOST -s https://api.elsanow.io/api/v1/asr -F "audio=@<path_to_your_file.wav>" --header "Authorization: ELSA <API_token>"
Asynchronous retrieval of functionality​

Example usage of the asynchronous usage. We start by calling the API with an audio file and retrieve from it the stream_id.

curl -XPOST -s https://api.elsanow.io/api/v1/score_audio_plus -F "api_plan=premium" -F "audio_file=@<path_to_your_file.wav>" --header "Authorization: ELSA <API_token>" -F "sync=false"

Here is an example of the result: 

{"stream_id":"<unique_stream_id>"}
Result endpoint​

To retrieve the result file (either as a download link or as json structure), call the result endpoint. 

curl -XGET "https://api.elsanow.io/result?stream_id=<unique_stream_id>" --header "Authorization: ELSA <API_token>"

Retrieve one result with json format​

Retrieve one result:

curl -XGET "https://api.elsanow.io/result?stream_id=<unique_stream_id>&return_json=true" --header "Authorization: ELSA <API_token>"

Retrieve multiple results together (in this option, we do not allow returning json in the call)

curl -XGET "https://api.elsanow.io/result?stream_id=<unique_stream_id>&stream_id=<unique_stream_id>" --header "Authorization: ELSA <API_token>"
Audio endpoint​

To retrieve the audio file:

curl -XGET "https://api.elsanow.io/audio?stream_id=<unique_stream_id>" --header "Authorization: ELSA <API_token>"