API Reference

Request URL

Verb/Method

POST

URL Elements

https://(hostname)

Sample URL

https://revapi.reverieinc.com/

Header NameDescriptionIs 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

string

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:

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

  2. It is an optional parameter.

logging

string

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.

Request

ElementTypeIs Mandatory?Description

audio_file

file

Yes

Upload the audio file to obtain the transcript.

Note - audio_file length should be equal to or less than 300 seconds (5 minutes).

Response

ElementTypeDescription

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": ""
}

Last updated