Online Technical Documentation
The SoapBox Cloud Web Service is an API organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API success & failure. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all successful API responses.
This document is a guide to the basics of using our Speech Web Service Solutions. It covers the types of requests you can make to the various services, how to construct those requests, and how to handle their responses. We recommend that all users of our Speech Web Service Solutions read this guide and one of the associated tutorials before diving into the API itself.
Service Endpoint
A service endpoint is a base URL that specifies the network address of an API service. One service may have multiple service endpoints. This service has the following service endpoint and all URIs below are relative to this service endpoint:
https://api.soapboxlabs.com/v1/
Endpoint Interaction
Each of the three speech solutions listed above (Fluency, STT & Verification) can be interacted with both synchronously and asynchronously. The maximum duration of an audio file depends on whether you're sending a synchronous or asynchronous request:
Synchronous requests send audio data to the selected speech solution, performs an analysis on that data, and returns results after all audio has been processed. Synchronous requests are blocking, meaning that they must return a response before processing the next request. Our speech services typically process audio faster than real-time, processing 30 seconds of audio in approx. 15 seconds on average. Synchronous requests are limited to audio data of 1 minute or less in duration.
Asynchronous requests send audio data to the selected speech solution and immediately returns a HTTP 202 (Accepted) JSON response which contains a
result idandstatus_urifields. The request is added to a queue to be processed and once processed the result is made available for retrieval using the status_uri field. Further details on interacting with our Web Services in an asynchronous manner are available here. Asynchronous requests are limited to audio data of 2 minutes or less in duration.
For test purposes, Interacting with our Web Services in a synchronous manner is the simplest method.
Web Service requests contain configuration parameters as well as audio data. The following sections describe these type of recognition requests, the responses they generate, and how to handle those responses in more detail.
Endpoint Resources
Authentication
To successfully interact with the REST API you must first Authenticate. This section provides further detail on how to authenticate.
Speech-To-Text
Speech-To-Text is a speech service that transcribes spoken utterances in an audio file.
Fluency
Fluency is a speech service that transcribes spoken utterances (using STT) in an audio file and provides an extra layer of analysis.
Verification
Verification is a speech service that can be used to verify if a sound file contains expected target words or phrases.
API Response Codes
The Speech Verification service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates a failure in the request, and a 500 type response usually indicates an internal system error. Response codes are listed with the method.
Response Code | Response Message | Description |
|---|---|---|
| OK | Everything worked as expected. |
| Accepted | The request was Accepted and will be processed (used by the async service) |
| Bad Request | The request was unacceptable, often due to missing a required parameter. |
| Unauthorized | Invalid API key provided. |
| Request Failed | The parameters were valid but the request failed. |
| Forbidden | The client is forbidden from accessing the specified service. |
| Not Found | The requested resource doesn't exist. This could be because it is not yet available (async) or will never be available |
| Conflict | The request conflicts with another request. |
| Payload Too Large | The request payload was too large. This typically occurs when the attached audio file is too large |
| Too Many Requests | Too many requests hit the API too quickly. |
| Server Error | Something went wrong on our end. This could be a 500, 502, 503, 504 depending on where the issue occurred |
JSON Envelopes
All successful API calls return JSON response envelopes. Visit the relevant API Docs or Sample Responses for more detail on the JSON returned.
Cross Origin Resource Sharing (CORS)
We support cross-origin resource sharing (CORS), allowing you to interact securely with our API from a client-side web application such as a browser.
CORS support is locked down to specific client domains. If you require CORS Support please contact us to have your domain added to our whitelist.