How Does API Work?

The process to transcribe an audio file:

Post the request by:
- Enter the valid REV-APPNAME, REV-APP-ID, and REV-API-KEY.
- Define the Language Code and domain.
- Upload the audio file to transcribe.
- Define the audio format, if required.
The API will return the text in the requested Indian language.

cURL for Integration

Step 1 : Upload the Audio File

Request : Transcribing Audio

curl --location --request POST 'https://revapi.reverieinc.com/upload' \
--header 'src_lang: hi' \
--header 'domain: generic' \
--header 'REV-API-KEY: <YOUR API KEY>' \
--header 'REV-APPNAME: stt_batch' \
--header 'REV-APP-ID: <YOUR API-ID>' \
--header 'subtitles: true' \
--form 'file=@"<File Path>"'

Request: Transcribing Audio other than Default Format

curl --location --request POST 'https://revapi.reverieinc.com/upload' \
--header 'src_lang: hi' \
--header 'domain: generic' \
--header 'REV-API-KEY: <YOUR API KEY>' \
--header 'REV-APPNAME: stt_batch' \
--header 'REV-APP-ID: <YOUR API-ID>' \
--header 'subtitles: true' \
--form 'file=@"<File Path>"' \
--header 'format=mp3'

Response: Success

{
    "job_id": "e21f356d-cbf9-4d62-a960-1e9da1805d19",
    "code": "000",
    "message": "Success. Request accepted"
}

Response: Error Message

{
    "job_id": "9b46fa98-d5a6-49d3-96c2-c12c22cf1984",
    "code": "005",
    "message": "file is required"
}

Step 2 : Get the Status

Request: Get status of the transcription

curl --location --request GET 'https://revapi.reverieinc.com/status?job_id=<job_id>' \
--header 'REV-API-KEY: <YOUR API KEY>' \
--header 'REV-APPNAME: stt_batch' \
--header 'REV-APP-ID: <YOUR API-ID>'

Response: Success

{
    "job_id": "e21f356d-cbf9-4d62-a960-1e9da1805d19",
    "code": "000",
    "message": "Transcript ready.",
    "status": "completed"
}

Step 3 : Get the Transcript

Request: Get transcript of the transcription

curl --location --request GET 'https://revapi.reverieinc.com/transcript?job_id=<job_id>' \
--header 'REV-API-KEY: <YOUR API KEY>' \
--header 'REV-APPNAME: stt_batch' \
--header 'REV-APP-ID: <YOUR API-ID>'

Response: Success

{
    "job_id": "e21f356d-cbf9-4d62-a960-1e9da1805d19",
    "code": "000",
    "message": "Transcript ready.",
    "result": {
        "transcript": "Hello. Welcome to Reverie.",
        "original_transcript": "HELLO. WELCOME TO REVERIE.",
        "channel_number": 1,
        "words": [
            [
                {
                    "conf": 0.991683,
                    "end": 0.21,
                    "start": 0.09,
                    "word": "HELLO"
                },
                {
                    "conf": 1.0,
                    "end": 0.6,
                    "start": 0.21,
                    "word": "WELCOME"
                },
                {
                    "conf": 0.99723,
                    "end": 0.72,
                    "start": 0.6,
                    "word": "TO"
                },
                {
                    "conf": 1.0,
                    "end": 1.320315,
                    "start": 0.72,
                    "word": "REVERIE"
                }
            ]
        ],
        "subtitles": "1\n00:00:00,090 --> 00:00:06,900\nHELLO. WELCOME TO REVERIE.\n\n"
    }
}

API References

HTTP Request URL

URL Elements	Sample URL
https://(hostname)	https://revapi.reverieinc.com/upload

Headers

string

required

API key shared by the Reverie team

string

required

APP ID shared by the Reverie team

string

required

Value if this string should always be stt_batch

string

required

Specify the language code.
Example: hi
Refer to section Language Codes for valid language code.

string

required

This field identifies your use case type and set of the terminology defined for transcription.
e.g. for general audio is ‘generic’
It is only required for the first API i.e Upload File API.

string

Mention the audio sample rate and file format of the uploaded file.
Refer to section Supported Audio Formats for valid audio format code.
It is only required for the first API i.e Upload File API
Note:
- By default, the format = 16k_int16. (WAV, Signed 16 bit, 16,000 or 16K Hz).
- It is an optional parameter.

boolean

Enables subtitling from the audio file.

Query Parameter

file

required

An audio file for which the transcript is desired.

Response

string

A unique Identity number auto-assigned by the API for each request, to be used to fetch job status and transcripts.

string

Provides a message code which can be used to look up the nature of the response returned by the API.

string

Provides a brief description about the response returned by the API.

Handling Errors

Our API raises errors when there is something wrong with certain aspects of the submitted file or any network issues. Some areas where errors might come up would be errors due to network related issues, file formats, incorrect domain names or language codes. Each response code provides a descriptive message about what has gone wrong.

API Response Message Codes

Code	Message
000	Success. Request accepted
001	Language code is required
002	File type not supported. Upload only wav, flac or mp3 formats. Preferred format for transcription is wav files
003	Language and/or Domain not available
004	File type not supported. Upload only wav, flac or mp3 formats. Preferred format for transcription is wav files
999	Unknown error, please contact developer

HTTP Status URL

URL Elements	Sample URL
https://(hostname)	`https://revapi.reverieinc.com/status?job_id=<job_id>`

Query Parameter

string

required

job_id received after uploading the file.

Status Query Response

string

A unique Identity number auto-assigned by the API for each request

string

Provides a message code which can be used to look up the nature of the response returned by the API

string

Provides a brief description about the response returned by the API.

string

status values: queued, processing, failed and completed

Status Types

Status	Description
queued	When the file is successfully validated, the request is queued for processing.
processing	The transcript generation process is in progress.
failed	Due to network issues, availability constraints, etc., the request might fail during processing.
completed	Transcription was successfully completed.

API Response Message Codes

Code	Message
000	Transcript ready
001	Invalid JOB ID
002	Invalid JOB ID
003	Your request is in the queue and will be processed shortly
004	Your request is being processed
005	Job failed. Please contact the developers
999	Unknown error

HTTP Transcript URL

URL Elements	Sample URL
https://(hostname)	`https://revapi.reverieinc.com/transcript?job_id=<job_id>`

Query Parameter

string

required

job_id received after uploading the file.

Transcript Query Response

string

A unique Identity number auto-assigned by the API for each request.

string

Provides a message code which can be used to look up the nature of the response returned by the API.

string

Provides a brief description about the response returned by the API.

string

An array of transcript objects including, channel_number, transcript, list of words with start time, end time and confidence.Please check the sample response.

API Response Message Codes

Code	Message
000	Transcript ready
001	Invalid JOB ID
002	Invalid JOB ID
003	Your request is in the queue and will be processed shortly
004	Your request is being processed
005	Job failed. Please contact the developers
999	Unknown error

Getting Started

Usage Guides

API References

Use Cases

SDKs

Endpoints

Speech-to-Text (Batch) API

How Does API Work?

cURL for Integration

Step 1 : Upload the Audio File

Request : Transcribing Audio

Request: Transcribing Audio other than Default Format

Response: Success

Response: Error Message

Step 2 : Get the Status

Request: Get status of the transcription

Response: Success

Step 3 : Get the Transcript

Request: Get transcript of the transcription

Response: Success

API References

HTTP Request URL

Headers

Query Parameter

Response

Handling Errors

API Response Message Codes

HTTP Status URL

Query Parameter

Status Query Response

Status Types

API Response Message Codes

HTTP Transcript URL

Query Parameter

Transcript Query Response

API Response Message Codes

​How Does API Work?

​cURL for Integration

​Step 1 : Upload the Audio File

​Request : Transcribing Audio

​Request: Transcribing Audio other than Default Format

​Response: Success

​Response: Error Message

​Step 2 : Get the Status

​Request: Get status of the transcription

​Response: Success

​Step 3 : Get the Transcript

​Request: Get transcript of the transcription

​Response: Success

​API References

​HTTP Request URL

​Headers

​Query Parameter

​Response

​Handling Errors

​API Response Message Codes

​HTTP Status URL

​Query Parameter

​Status Query Response

​Status Types

​API Response Message Codes

​HTTP Transcript URL

​Query Parameter

​Transcript Query Response

​API Response Message Codes

How Does API Work?

cURL for Integration

Step 1 : Upload the Audio File

Request : Transcribing Audio

Request: Transcribing Audio other than Default Format

Response: Success

Response: Error Message

Step 2 : Get the Status

Request: Get status of the transcription

Response: Success

Step 3 : Get the Transcript

Request: Get transcript of the transcription

Response: Success

API References

HTTP Request URL

Headers

Query Parameter

Response

Handling Errors

API Response Message Codes

HTTP Status URL

Query Parameter

Status Query Response

Status Types

API Response Message Codes

HTTP Transcript URL

Query Parameter

Transcript Query Response

API Response Message Codes