> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reverieinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Speech-to-Text (File) API

> The Speech-to-Text API  powered by Reverie's AI technology accurately converts speech into text.  The solution can transcribe audio files of various Indian languages and audio formats.

# 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

```bash theme={null}
curl --location --request POST 'https://revapi.reverieinc.com/' \
--header 'src_lang: hi' \
--header 'domain: generic' \
--header 'REV-API-KEY: <YOUR API KEY>' \
--header 'REV-APPNAME: stt_file' \
--header 'REV-APP-ID: <YOUR API-ID>' \
--form 'audio_file=@"<File Path>"
```

#### Request: Transcribing Audio other than Default Format

```bash theme={null}
curl --location --request POST 'https://revapi.reverieinc.com/' \
--header 'src_lang: hi' \
--header 'domain: generic' \
--header 'REV-API-KEY: <YOUR API KEY>' \
--header 'REV-APPNAME: stt_file' \
--header 'REV-APP-ID: <YOUR API-ID>' \
--header 'format: mp3'
--form 'audio_file=@"<File Path>"'
```

#### Response: Success

```json theme={null}
{
    "id": "ddf4ebda44af4fdf95118af9a6f14d46fce12ed85347471d",
    "success": true,
    "final": true,
    "text": "नाइनटी एट पॉइंट थ्री एफएम पर प्ले करिए",
    "cause": "EOF received",
    "confidence": 0.891,
    "display_text": "98.3 एफएम पर प्ले करिए"
}
```

#### Response: Error Message

```json theme={null}
{
    "id": "03e4f260551345e6832bf62ba273e0096fd303e72f94453f",
    "success": false,
    "text": "",
    "final": true,
    "confidence": 1.0,
    "cause": "no file given",
    "display_text": ""  }
```

## API References

### HTTP Request URL

| URL Elements | Sample URL |
| - | - |
| https\://(hostname) | [https://revapi.reverieinc.com/](https://revapi.reverieinc.com/) |

#### Headers

**REV-API-KEY** `string` *required*

&#x20;

API key shared by the Reverie team

**REV-APP-ID** `string` *required*

&#x20;

APP ID shared by the Reverie team

**REV-APPNAME** `string` *required*

&#x20;

Value if this string should always be `stt_file`

**src\_lang** `string` *required*

&#x20;

* Specify the language code.  \\

* Example: `hi` \\

* Refer to section [Language Codes](https://docs.reverieinc.com/usage-guides/speech-to-text/supported-languages.md) for valid language code.

**domain** `string` *required*

&#x20;

* 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`

&#x20;

* Mention the audio sample rate and file format of the uploaded file.    \\

* Refer to section [Supported Audio Formats](https://docs.reverieinc.com/usage-guides/speech-to-text/supported-audio-formats.md) 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.

#### Query Parameter

**audio\_file** `file` *required*

&#x20;

* An audio file for which the transcript is desired.

#### Response

**id** `string`

&#x20;

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

**success** `boolean`

&#x20;

* Provides true or false based on the nature of the response returned by the API.

**final** `boolean`

&#x20;

* Provides whether the response is the final response returned by the API.

**text** `string`

&#x20;

* Provides the trascripted response returned by the API for the audio file.

**cause** `string`

&#x20;

* Reason for obtaining the final output, generally due to End Of File (EOF) received.

**confidence** `float`

&#x20;

* Provides the confidence on the scale of 0 - 1 for the output.

**display\_text** `string`

&#x20;

* Provides the display text for the final output based on some post processing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.