API Reference

Request URL

Verb/Method

POST

URL Elements

wss://(host_name)/stream?appname=stt_stream&apikey=(your_api_key)&appid=(your_app-id)&domain=(domain_name)&src_lang=(language_code)&timeout=(time_in_seconds)&silence=(time_in_seconds)&format=(audio_format)

Sample URL

wss://revapi.reverieinc.com/stream?apikey=&appid=&appname=stt_stream&src_lang=hi&domain=generic&timeout=120&silence=5

Query Parameter

Element	Type	Is Mandatory?	Description
apikey	string	Yes	A unique key/token is provided by Reverie to identify the user using the STT API.
appid	string	Yes	A unique account ID to identify the user and the default account settings
appname	string	Yes	The parameter to identify the API. Note: The value allowed is stt_stream
src_lang	string	Yes	Indicates the language in which the audio is spoken. Specify the ISO language code. Example: "hi" Refer to section Language Codes for valid language code.
domain	string	Yes	The universe in which the Streaming STT API is used for transcribing the speech. Specify the domain ID. Refer to Speech to Text \| Streaming APISupporting Domain section for valid domain ID.
timeout	float	No	The duration to keep a connection open between the application and the STT server. Note: The default timeout = 15 seconds, and the maximum time allowed = 180 seconds
silence	float	No	The time to determine when to end the connection automatically after detecting the silence after receiving the speech data. Example: Consider silence = 15 seconds i.e., On passing the speech for 60 seconds, and if you remain silent, the connection will be open for the next 15 seconds and then will automatically get disconnected. Note: The default silence= 1 second, and the maximum silence = 30 seconds.
format	string	No	The audio sampling rate and the data format of the speech. Refer to section Supporting Audio Format section to know the supporting audio formats. Note: By default, the format = 16k_int16. (WAV, Signed 16 bit, 16,000 or 16K Hz).

Element

Type

Is Mandatory?

Description

apikey

string

Yes

A unique key/token is provided by Reverie to identify the user using the STT API.

appid

string

Yes

A unique account ID to identify the user and the default account settings

appname

string

Yes

The parameter to identify the API.

Note: The value allowed is stt_stream

src_lang

string

Yes

Indicates the language in which the audio is spoken.

Specify the ISO language code.

Example: "hi"

Refer to section Language Codes for valid language code.

domain

string

Yes

The universe in which the Streaming STT API is used for transcribing the speech.

Specify the domain ID.

Refer to Speech to Text | Streaming APISupporting Domain section for valid domain ID.

timeout

float

The duration to keep a connection open between the application and the STT server.

Note: The default timeout = 15 seconds, and the maximum time allowed = 180 seconds

silence

float

The time to determine when to end the connection automatically after detecting the silence after receiving the speech data.

Example:

Consider silence = 15 seconds

i.e., On passing the speech for 60 seconds, and if you remain silent, the connection will be open for the next 15 seconds and then will automatically get disconnected.

Note: The default silence= 1 second, and the maximum silence = 30 seconds.

format

string

The audio sampling rate and the data format of the speech.

Refer to section Supporting Audio Format section to know the supporting audio formats.

Note: By default, the format = 16k_int16. (WAV, Signed 16 bit, 16,000 or 16K Hz).

Request

Element	Type	Is Mandatory?	Description
streaming audio	binary	Yes	The audio streamed from the input device. Note: The default timeout = 15 seconds, and the maximum time allowed = 180 seconds.

Element

Type

Is Mandatory?

Description

streaming audio

binary

Yes

The audio streamed from the input device.

Note: The default timeout = 15 seconds, and the maximum time allowed = 180 seconds.

Response

Element	Type	Description
id	string	API will auto-assign assign a unique identification number for each request.
success	boolean	Will indicate the functional status of the API: If the success = true, then the API is functioning and ready to generate output. If the success = false, then the API is not functional and has some errors
final	boolean	Will report whether the received output is partial or final: If the final = true, then the received text is the final output. If the final = false, then the text received is partial and is still processing the file.
cause	string	Reason for obtaining the final output. The cause will appear for both successful and failed requests; Refer to section API Messages to view the list of messages/ cause and its description.
text	string	The streaming audio input is converted into text format in the requested language. Note: The field will remain empty in case of any error or on connect.
confidence	float	The level of confidence that Streaming STT API has in the accuracy of the transcription. The Confidence score ranges from “0” to “1”. Higher scores indicate greater relevance to the transcription
display_text	string	The beautified text of the final transcript. If the final transcript consists of digits, URL, app names, it is quickly converted to a readable format for the user. Note: The field will remain empty in case of any error or on connect

Element

Type

Description

string

API will auto-assign assign a unique identification number for each request.

success

boolean

Will indicate the functional status of the API:

If the success = true, then the API is functioning and ready to generate output.

If the success = false, then the API is not functional and has some errors

final

boolean

Will report whether the received output is partial or final:

If the final = true, then the received text is the final output.

If the final = false, then the text received is partial and is still processing the file.

cause

string

Reason for obtaining the final output.

The cause will appear for both successful and failed requests;

Refer to section API Messages to view the list of messages/ cause and its description.

text

string

The streaming audio input is converted into text format in the requested language.

Note: The field will remain empty in case of any error or on connect.

confidence

float

The level of confidence that Streaming STT API has in the accuracy of the transcription.

The Confidence score ranges from “0” to “1”. Higher scores indicate greater relevance to the transcription

display_text

string

The beautified text of the final transcript.

If the final transcript consists of digits, URL, app names, it is quickly converted to a readable format for the user.

Note: The field will remain empty in case of any error or on connect

Handling Error

The Streaming STT API raises exceptions for many reasons, such as a failed connection, invalid parameters, authentication errors, and network unavailability. We provide more specific human-readable messages with an error response so that users can react to errors more.

In the API response, if the success = false, then the cause will display the reason for the error. Refer to Appendix C: API Messages to view the list of error messages and its description.

{
  "id": "2ab3a0b76c854953a022df742f6b3857a76494acd72e4489",
  "success": false,
  "text": "",
  "final": true,
  "confidence": 1,
  "cause": "no `domain` given"
}

PreviousSetup NextLanguage Codes

Last updated 9 months ago