API Reference

Request URL

Verb/Method	POST
URL Elements	https://(hostname)
Sample URL	https://revapi.reverieinc.com/

Header

Header Name	Description	Is Mandatory?	Value
REV-API-KEY	A unique key/token is provided by Reverie to identify the user using the STT API	Yes	-
REV-APP-ID	The unique account ID to identify the user and the default account settings	Yes	-
REV-APPNAME	The parameter to identify the API	Yes	stt_file
domain	Refer to the universe in which the STT API is used for transcribing the audio file Example: Banking, Insurance, etc.	Yes	Specify the domain code. Refer to Supporting Domain section for valid domain ID.
src_lang	Indicates the language in which the audio is spoken	Yes	Specify the language code. Refer to Language Code section for valid language code.
format	Indicates the supporting format of the audio file	No	Mention the audio sample rate and file format of the uploaded file. Refer to the 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). It is an optional parameter.
logging	Indicates the type of logging of data you can choose	No	Default value=true Possible values are : 1. true - stores client’s audio and keeps transcript in logs. 2. no_audio - does not store client’s audio but keeps transcript in logs. 3. no_transcript - does not keep transcript in logs but stores client’s audio. 4. false - does not keep neither client’s audio nor transcript in log.
punctuate	Indicates whether capitalisation and punctuation is needed in the transcript	No	It will enable punctuation and capitalisation in the transcript. The values it can take are true and false. Supported languages: en, hi Default value is true

Request

Element	Type	Description
audio_file	file	Upload the audio file to obtain the transcript. Note - audio_file length should be equal to or less than 300 seconds (5 minutes).
file_url	file URL	The audio file’s public URL to obtain the transcript. Note - file_url length should be equal to or less than 300 seconds (5 minutes).

Note - Either one of audio_file or file_url should be mandatory in the request.

Response

Element	Type	Description
id	string	API will auto-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 the API Messages section to view the list of messages/ cause and its description.
text	string	The audio file transcribed 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 Reverie 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 Errors

The 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.

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

{
    "id": "0ca5c7293d1d4eaaa5eb5ade8331dd3300443509daf8434b",
    "success": false,
    "text": "",
    "final": true,
    "confidence": 1.0,
    "cause": "no `domain` given",
    "display_text": ""
}