​
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 ElementsSample URL
https://(hostname)https://revapi.reverieinc.com/upload

​
Headers

​
REV-API-KEY
string
required

API key shared by the Reverie team

​
REV-APP-ID
string
required

APP ID shared by the Reverie team

​
REV-APPNAME
string
required

Value if this string should always be stt_batch

​
src_lang
string
required
  • Specify the language code.
  • Example: hi
  • Refer to section Language Codes for valid language code.
​
domain
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.
​
format
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.
​
subtitles
boolean
  • Enables subtitling from the audio file.

​
Query Parameter

​
file
file
required
  • An audio file for which the transcript is desired.

​
Response

​
job_id
string
  • A unique Identity number auto-assigned by the API for each request, to be used to fetch job status and transcripts.
​
code
string
  • Provides a message code which can be used to look up the nature of the response returned by the API.
​
message
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

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

​
HTTP Status URL

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

​
Query Parameter

​
job_id
string
required
  • job_id received after uploading the file.

​
Status Query Response

​
job_id
string
  • A unique Identity number auto-assigned by the API for each request
​
code
string
  • Provides a message code which can be used to look up the nature of the response returned by the API
​
message
string
  • Provides a brief description about the response returned by the API.
​
status
string
  • status values: queued, processing, failed and completed

​
Status Types

StatusDescription
queuedWhen the file is successfully validated, the request is queued for processing.
processingThe transcript generation process is in progress.
failedDue to network issues, availability constraints, etc., the request might fail during processing.
completedTranscription was successfully completed.

​
API Response Message Codes

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

​
HTTP Transcript URL

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

​
Query Parameter

​
job_id
string
required
  • job_id received after uploading the file.

​
Transcript Query Response

​
job_id
string
  • A unique Identity number auto-assigned by the API for each request.
​
code
string
  • Provides a message code which can be used to look up the nature of the response returned by the API.
​
message
string
  • Provides a brief description about the response returned by the API.
​
result
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

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