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

# Getting Started

> An introduction to getting transcription data from pre-recorded audio files.

This guide will walk you through how to transcribe pre-recorded audio with the Reverie API. We provide two scenarios to try: transcribe a remote file and transcribe a local file.

> [!NOTE]
>
> Before you start, you'll need to follow the steps in the [Get your API
> Credentials](https://docs.reverieinc.com/authentication.md) to obtain your API key.

## Make your first Call

Make your first API Call using the cURL request. Add your own API Credentials where it says `<YOUR-APP-ID>` & `<YOUR-API-KEY>`
and then run the following example in a terminal or your favorite API client.

## Step 1 : Upload the Audio File

Upload the Audio File to the API.

### Request: Transcribing Audio

```bash theme={null}
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>"'
```

### Response: Success

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

In the response, you will receive `job_id`. Please note it.

## Step 2 : Get the Status

Send the `job_id` received in the Step 1 as the query parameter to know the status of the ongoing process of transcription.

### Request: Get status of the transcription

```bash theme={null}
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

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

In the response, you will receive `status` = `completed` and `message` = `Transcript ready` once the transcription is complete. Otherwise, you will receive `status` = `applying`.

## Step 3 : Get the Transcript

Once the `status` = `completed` in the Step 2, You can use the `job_id` received in the Step 1 or Step 2 as the query parameter to get the Transcript.

### Request: Get transcript of the transcription

```bash theme={null}
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

```json theme={null}
{
    "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"
    }
}
```

In this response we see:

* `job_id` : A unique Identity number auto-assigned by the API for each request.
* `code` : Provides a message code which can be used to look up the nature of the response returned by the API.
* `message` :Provides a brief description about the response returned by the API.
* `result` : An array of transcript objects including, channel\_number, transcript, list of words with start time, end time and confidence.Please check the sample response.

## SDKs

Reverie has several SDKs that can make it easier to use the API.
Follow these steps to use the SDK of your choice to make a Reverie Speech-to-Text request.

## Install Dependencies

```bash JavaScript theme={null}
npm i @reverieit/reverie-client
```

```bash Python theme={null}
pip install reverie-sdk
```

## Transcribe Audio from an Audio File

To automatically transcribe pre-recorded audio using Reverie’s SDK, follow these steps

```javascript Javascript theme={null}
const ReverieClient = require("@reverieit/reverie-client");

const reverieClient = new ReverieClient({
apiKey: "YOUR-API-KEY",
appId: "YOUR-APP-ID",
});

const response = await reverieClient.stt_batch({
audioFile: file,
language: lang,
subtitles: subtitles
});

console.log("Response from API:", response);

```

```python Python theme={null}
from reverie_sdk import ReverieClient

client = ReverieClient(
    api_key="<YOUR API KEY>",
    app_id="<YOUR APP ID>",
)

resp = client.asr.stt_file(
    src_lang="en",
    data=open("./path/to/audio.wav", "rb").read(),
)
print(resp)
```

```go GoLang theme={null}
package main

import (
"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"mime/multipart"
	"net/http"
	"os"
)

const (
	apiURL     = "https://revapi.reverieinc.com/"
	apiKey     = "your_api_key"   
	appID      = "your_app_id"
	appName    = "stt_file"
	srcLang    = "en"
	domain     = "generic"
	audioPath  = "audio.wav"
)

type ApiResponse struct {
	DisplayText string `json:"display_text"`
}

func transcribeAudio(filePath string) (string, error) {
	file, err := os.Open(filePath)
	if err != nil {
		return "", fmt.Errorf("error opening file: %v", err)
	}
	defer file.Close()

	var requestBody bytes.Buffer
	writer := multipart.NewWriter(&requestBody)
	part, err := writer.CreateFormFile("audio_file", filePath)
	if err != nil {
		return "", fmt.Errorf("error creating form file: %v", err)
	}

	fileBytes, err := ioutil.ReadAll(file)
	if err != nil {
		return "", fmt.Errorf("error reading file: %v", err)
	}
	part.Write(fileBytes)
	writer.Close()

	req, err := http.NewRequest("POST", apiURL, &requestBody)
	if err != nil {
		return "", fmt.Errorf("error creating request: %v", err)
	}

	req.Header.Set("src_lang", srcLang)
	req.Header.Set("domain", domain)
	req.Header.Set("REV-API-KEY", apiKey)
	req.Header.Set("REV-APPNAME", appName)
	req.Header.Set("REV-APP-ID", appID)
	req.Header.Set("Content-Type", writer.FormDataContentType())

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("error sending request: %v", err)
	}
	defer resp.Body.Close()

	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return "", fmt.Errorf("error reading response: %v", err)
	}

	var apiResponse ApiResponse
	if err := json.Unmarshal(body, &apiResponse); err != nil {
		return "", fmt.Errorf("error parsing JSON: %v", err)
	}

	return apiResponse.DisplayText, nil
}

func main() {
	transcription, err := transcribeAudio(audioPath)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	fmt.Println("Transcription:", transcription)
}
```

## Results

In order to see the results from Reverie, you must run the application. Run your application from the terminal. Your transcripts will appear in your shell.

```bash JavaScript theme={null}
# Run your application using the file you created in the previous step
# Example:
npm start
```

```python Python theme={null}
# Run your application using the file you created in the previous step
# Example:
python main.py
```

```go GoLang theme={null}
// Run your application using the file you created in the previous step
// Example:
go run main.go
```

## Analyzing the Response

```json theme={null}
{
  "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"
  }
}
```

In this response we see:

* `job_id` : A unique Identity number auto-assigned by the API for each request.
* `code` : Provides a message code which can be used to look up the nature of the response returned by the API.
* `message` :Provides a brief description about the response returned by the API.
* `result` : An array of transcript objects including, channel\_number, transcript, list of words with start time, end time and confidence.Please check the sample response.


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