Web Service Interaction Methods

This page provides more detail on interacting with our Web Services using the currently available methods.

Synchronous

Interacting with the SoapBox Labs Web Service synchronously is generally the most straightforward method. A synchronous request is blocking, meaning that the Web Service must return a response before processing the next request (the connection remains open and waits for the request to be processed).

Example CURL Interaction

The following is an example STT API interaction using CURL:

The Speech-To-Text API synchronous Speech service is located at:

https://api.soapboxlabs.com/v1/speech/recognition

For quick tests you can use a tool called CURL (Mac & Linux) and the following sample CURL command...

curl -X POST \
    -H "x-app-key:$APP_KEY" \
    -F "file=@$AUDIO_FILE" \
    -F "user_token=$USER_TOKEN" \
    -F "model_id=$MODEL_ID" \
    https://api.soapboxlabs.com/v1/speech/recognition

In the above request, an audio file is submitted to the STT API, targeting a Custom Domain (CLM) via the MODEL_ID. The speech contained in the audio file will be transcribed and a JSON response will be generated and returned.

For a fuller explanation of the STT JSON response structure shown here, please refer to the following article.

Asynchronous

Each of our main Speech Solutions can be also be interacted with in an asynchronous manner. With an asynchronous interaction, an initial request is sent (POST) to decode an audio file. A response is returned immediately with a HTTP Code of 202 and a JSON result that contains a RESULT_ID. The request is added to a queue to be processed. Once the result is ready it is retrievable using a GET request to the Results endpoint specifying the RESULT_ID. The length of time it takes to process the audio file (and therefore have a result available) is dependent on the volume of requests submitted and the duration of the audio file. 

A diagram showing a typical asynchronous interaction
Typical asynchronous interaction

Example CURL Interaction

The following is an example STT API interaction using CURL:

The Speech-To-Text API asynchronous Speech service is located at...

https://api.soapboxlabs.com/v1/async/request/speech/recognition

For quick tests you can use a tool called CURL (Mac & Linux) and the following sample CURL command...

curl -X POST \
    -H "x-app-key:$APP_KEY" \
    -F "file=@$AUDIO_FILE" \
    -F "user_token=$USER_TOKEN" \
    -F "model_id=$MODEL_ID" \
    https://api.soapboxlabs.com/v1/async/request/speech/recognition

In the above request, an audio file is submitted to the STT API, targeting a Custom Domain (CLM) via the MODEL_ID. The speech contained in the audio file will be transcribed and a JSON response will be generated and returned as follows:

{"id":"f0840fac-3006-48ae-b97e-b4beceeecbb5","status_uri":"https://api.soapboxlabs.com/v1/async/results/f0840fac-3006-48ae-b97e-b4beceeecbb5"}

The JSON contains a request id and link (status_uri) to where the result of the request will be stored once processed. This result can then be retrieved by using the full status_uri field as follows:

curl https://api.soapboxlabs.com/v1/async/results/f0840fac-3006-48ae-b97e-a4beceeecbb5

For a fuller explanation of the STT JSON response structure shown here, please refer to the following article.

Search