> For the complete documentation index, see [llms.txt](https://dibd-bhashini.gitbook.io/bhashini-apis/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dibd-bhashini.gitbook.io/bhashini-apis/pipeline-compute-call/request-payload.md).

# Request Payload

## Request Payload for Individual Task

{% tabs %}
{% tab title="ASR" %}
{% code lineNumbers="true" %}

```json
{
    "pipelineTasks": [
        {
            "taskType": "asr",
            "config": {
                "language": {
                    "sourceLanguage": "xx"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--dddd",
                "audioFormat": "wav",
                "samplingRate": 16000,
                "preProcessors": [
                    "vad"
                ],
                "postProcessors": [
                    "itn"
                ]
            }
        }
    ],
    "inputData": {
        "input": [
            {
                "source": null
            }
        ],
        "audio": [
            {
                "audioContent": "{{generated_base64_content}}"
            }
        ]
    }
}
```

{% endcode %}

This response contains 2 major parameters listed below and detailed further down the section:

1. pipelineTasks
2. inputData

### Parameter: `pipelineTasks`

**Type:** Array\
\
This parameter takes an array of tasks, in the form of dictionary of **`taskType`** and **`config`**, that are to be done by the integrator. \
In the above example, **`pipelineTasks`** takes only one dictionary (line 3-13) because integrator wants to do only ASR.\
\
**`taskType`** parameter takes `String` that takes the value **`asr`**

**`config`** parameter takes a **`Dictionary`** that contains following parameters:

{% tabs %}
{% tab title="Language" %}
For ASR, **`language`** parameter only takes **`sourceLanguage`** which accepts [ISO-639 Series Code](/bhashini-apis/overall-understanding-of-the-api-calls.md) of the language.
{% endtab %}

{% tab title="Service ID" %}
serviceId parameter is obtained from the [Pipeline Config Call](/bhashini-apis/pipeline-config-call.md) [response](/bhashini-apis/pipeline-config-call/response-payload.md) as described [here](/bhashini-apis/pipeline-config-call/response-payload.md#parameter-pipelineresponseconfig).
{% endtab %}

{% tab title="Audio Format" %}
**`audioFormat`** parameter accepts format of the audio which was recorded by the application.

* For Android, **`wav`** is preferred and
* For iOS, **`wav`** or **`flac`** is preferred. 

However, the Server also accepts other well -known formats such as **`mp3`**.
{% endtab %}

{% tab title="Sampling Rate" %}
Sampling Rate is determined by the application at which the audio is recorded. The Server accepts a minimum value of **`8000`** for **`samplingRate`** parameter.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Parameters other than **`taskType`**, **`serviceId`** and **`config`** are optional.
{% endhint %}

### Parameter: `inputData`

inputData Parameter takes the actual input from the integrator on which the individual task has to be done. It can take the input either via **`input`** parameter or **`audio`** parameter depending on the task to be done.\
Since ASR is done on audio input data, for ASR, 

* **`input`** parameter is optional, of no use for ASR but
* **`audio`** parameter is mandatory.

**audio** parameter takes **`audioContent`** parameter which accepts **`base64 String`** of the actual audio captured. 

{% hint style="info" %}
If **`audioFormat`** or/and **`samplingRate`** parameter is/are sent, integrator should make sure that these values correspond to the actual recorded audio.
{% endhint %}
{% endtab %}

{% tab title="Translation" %}
{% code lineNumbers="true" %}

```json
{
    "pipelineTasks": [
        {
            "taskType": "translation",
            "config": {
                "language": {
                    "sourceLanguage": "hi",
                    "targetLanguage": "en"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--dddd",
                "numTranslation": "True"
            }
        }
    ],
    "inputData": {
        "input": [
            {
                "source": "मेरा नाम विहिर है और मैं भाषाावर्ष यूज कर रहा हूँ"
            }
        ],
        "audio": [
            {
                "audioContent": null
            }
        ]
    }
}
```

{% endcode %}

This response contains 2 major parameters listed below and detailed further down the section:

1. pipelineTasks
2. inputData

### Parameter: `pipelineTasks`

**Type:** Array\
\
This parameter takes an array of tasks, in the form of dictionary of **`taskType`** and **`config`**, that are to be done by the integrator. \
In the above example, **`pipelineTasks`** takes only one dictionary (line 3-12) because integrator wants to do only Translation.\
\
**`taskType`** parameter takes `String` that takes the value **`translation`**

**`config`** parameter takes a **`Dictionary`** that contains following parameters:

{% tabs %}
{% tab title="Language" %}
For Translation, **`language`** parameter takes both **`sourceLanguage`** and **`targetLanguage`** which accepts [ISO-639 Series Code](https://bhashini.gitbook.io/bhashini-apis/)[ ](/bhashini-apis/overall-understanding-of-the-api-calls.md)of the language.
{% endtab %}

{% tab title="Service ID" %}
serviceId parameter is obtained from the [Pipeline Config Call](/bhashini-apis/pipeline-config-call.md) [response](/bhashini-apis/pipeline-config-call/response-payload.md) as described [here](/bhashini-apis/pipeline-config-call/response-payload.md#parameter-pipelineresponseconfig).
{% endtab %}

{% tab title="numTranslation" %}
numTranslation is a optional parameter which enable the API to translate the numerical data/digit into the respective target language.

this feature is currently enabled only in **ai4bharat/indictrans-v2-all-gpu--t4** service Id and for devanagari script supported languages. Default value is False.
{% endtab %}
{% endtabs %}

### Parameter: `inputData`

inputData Parameter takes the actual input from the integrator on which the individual task has to be done. It can take the input either via **`input`** parameter or **`audio`** parameter depending on the task to be done.\
Since Transaltion is done on digital text input data, for Translation, 

* **`input`** parameter is mandatory and
* **`audio`** parameter is optional and of no use for Translation.

**input** parameter takes **`source`** parameter which accepts **`digital text string`**. 
{% endtab %}

{% tab title="TTS" %}
{% code lineNumbers="true" %}

```json
{
    "pipelineTasks": [       
        {
            "taskType": "tts",
            "config": {
                "language": {
                    "sourceLanguage": "gu"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--dddd",
                "gender": "female",
                "speed": 1.0, // range between 0.1 to 1.99
                "samplingRate": 48000               
            }
        }
    ],
    "inputData": {
        "input": [
            {
                "source": "મારું નામ વિહીર છે અને હું ભાષાવર્ષનો ઉપયોગ કરી રહ્યો છું"
            }
        ],
        "audio": [
            {
                "audioContent": null
            }
        ]
    }
}
```

{% endcode %}

This response contains 2 major parameters listed below and detailed further down the section:

1. pipelineTasks
2. inputData

### Parameter: `pipelineTasks`

**Type:** Array\
\
This parameter takes an array of tasks, in the form of dictionary of **`taskType`** and **`config`**, that are to be done by the integrator. \
In the above example, **`pipelineTasks`** takes only one dictionary (line 3-12) because integrator wants to do only TTS.\
\
**`taskType`** parameter takes `String` that takes the value **`tts`**

**`config`** parameter takes a **`Dictionary`** that contains following parameters:

{% tabs %}
{% tab title="Language" %}
For TTS, **`language`** parameter only takes **`sourceLanguage`** which accepts [ISO-639 Series Code](/bhashini-apis/overall-understanding-of-the-api-calls.md) of the language.
{% endtab %}

{% tab title="Service ID" %}
serviceId parameter is obtained from the [Pipeline Config Call](/bhashini-apis/pipeline-config-call.md) [response](/bhashini-apis/pipeline-config-call/response-payload.md) as described [here](/bhashini-apis/pipeline-config-call/response-payload.md#parameter-pipelineresponseconfig).
{% endtab %}

{% tab title="gender" %}
gender parameter takes a string input which can either be:

* male
* female

gender parameter tells the server that integrator is requesting the generated speech in either male or female voice.
{% endtab %}

{% tab title="speed" %}
speed parameter takes a integer input which helps in controlling on how fast the synthesized voice speaks. Range between 0.1 to 1.99

* Increased speed makes the speech sounds quicker, useful for fast-paced content like alerts or summaries.
* Decreased speed makes the speech is slower and more deliberate, ideal for accessibility or language learning.
  {% endtab %}

{% tab title="samplingRate" %}
samplingRate parameter takes a integer value which helps in determining the number of audio samples per second in the generated speech output, measured in Hertz (Hz). It's a key parameter that affects both audio quality and file size.
{% endtab %}
{% endtabs %}

### Parameter: `inputData`

inputData Parameter takes the actual input from the integrator on which the individual task has to be done. It can take the input either via **`input`** parameter or **`audio`** parameter depending on the task to be done.\
Since TTS is done on digital text input data, for TTS, 

* **`input`** parameter is mandatory and
* **`audio`** parameter is optional and of no use for TTS.

**input** parameter takes **`source`** parameter which accepts **`digital text string`**. 
{% endtab %}
{% endtabs %}

## Request Payload for Combination of Tasks in specific sequence

{% tabs %}
{% tab title="ASR+Translation" %}
{% code lineNumbers="true" %}

```json
{
    "pipelineTasks": [
        {
            "taskType": "asr",
            "config": {
                "language": {
                    "sourceLanguage": "xx"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--dddd",
                "audioFormat": "flac",
                "samplingRate": 16000
            }
        },
        {
            "taskType": "translation",
            "config": {
                "language": {
                    "sourceLanguage": "xx",
                    "targetLanguage": "yy"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--mfkds"
            }
        }
    ],
    "inputData": {
        "input": [
            {
                "source": null
            }
        ],
        "audio": [
            {
                "audioContent": "{{generated_base64_content}}"
            }
        ]
    }
}
```

{% endcode %}

### Parameter: `pipelineTasks`

**Type:** Array\
\
This parameter takes an array of tasks, in the form of dictionary of **`taskType`** and **`config`**, that are to be done by the integrator. \
In the above example, **`pipelineTasks`** takes two dictionaries:

* Line 3 to 13 i.e., **`ASR Dictionary`**
* Line 14 to 23 i.e., **`Translation Dictionary`**

because integrator wants to do **`ASR`** of the input voice followed by **`Translation`** of the digital text. 

**`Line Number 7`** and **`Line Number 18`** are connected with below understanding. Consider a use-case described below:

Integrator wants to **speak** in say **`Hindi`** language and wants to **see** the **translated output** in **`Marathi`**. For this to happen, integrator has to:

* Convert the Audio integrator has spoken to digital text i.e., ASR of Hindi
* Translate this digital Hindi text to Marathi digital text i.e., Translation from Hindi to Marathi

{% hint style="info" %}
Therefore, the **language code** for **`ASR`** that is to be inserted in **Line 7**, shall be **`hi`**, i.e., [ISO 639 series](/bhashini-apis/overall-understanding-of-the-api-calls.md) code for Hindi. Once this Hindi digital text is generated, the same shall be translated to Marathi, therefore the **source language code** for **`Translation`** that is to be inserted in **Line 18**, shall also be **`hi`**, which means that **language code** in **Line 7** and **Line 18** shall be same. 

For Target Language the code to be inserted in Line 19 shall be **`mr`**, i.e., [ISO 639 series](/bhashini-apis/overall-understanding-of-the-api-calls.md) code for Marathi.  
{% endhint %}

{% hint style="info" %}
Understanding of all other parameters remains same as described above in [**`Request Payload for Individual Task`**](#request-payload-for-individual-task).
{% endhint %}
{% endtab %}

{% tab title="Translation+TTS" %}

{% code lineNumbers="true" %}

```json
{
    "pipelineTasks": [
        {
            "taskType": "translation",
            "config": {
                "language": {
                    "sourceLanguage": "hi",
                    "targetLanguage": "yy"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--dddd"
            }
        },
        {
            "taskType": "tts",
            "config": {
                "language": {
                    "sourceLanguage": "yy"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--csdcxsa",
                "gender": "female"
            }
        }
    ],
    "inputData": {
        "input": [
            {
                "source": "मेरा नाम विहिर है और मैं भाषाावर्ष यूज कर रहा हूँ"
            }
        ],
        "audio": [
            {
                "audioContent": null
            }
        ]
    }
}
```

{% endcode %}

### Parameter: `pipelineTasks`

**Type:** Array\
\
This parameter takes an array of tasks, in the form of dictionary of **`taskType`** and **`config`**, that are to be done by the integrator. \
In the above example, **`pipelineTasks`** takes two dictionaries:

* Line 3 to 12 i.e., **`Translation Dictionary`**
* Line 13 to 22 i.e., **`TTS Dictionary`**

because integrator wants to do **`Translation`** of a digital text followed by **`TTS`**.

**`Line Number 8`** and **`Line Number 17`** are connected with below understanding. Consider a use-case described below:

Integrator wants to **translate** say from **`Hindi`** to **`Marathi`** language and wants to **hear** the **output** in **`Marathi`**. For this to happen, integrator has to:

* Translate this digital Hindi text to Marathi digital text i.e., Translation from Hindi to Marathi
* Generate this Marathi text speech i.e., TTS of the Marathi digital text. 

{% hint style="info" %}
Therefore, the **source language code** for **`Translation`** that is to be inserted in **Line 7**, shall be **`hi`**, i.e., [ISO 639 series](/bhashini-apis/overall-understanding-of-the-api-calls.md) code for Hindi. The **target language code** to be inserted in Line 8 shall be **`mr`**, i.e., [ISO 639 series](/bhashini-apis/overall-understanding-of-the-api-calls.md) code for Marathi.

Speech shall be generated in Marathi which means the language code to be inserted in **Line 17** shall be **`mr`**, same as **Line 8.** 
{% endhint %}

{% hint style="info" %}
Understanding of all other parameters remains same as described above in [**`Request Payload for Individual Task`**](#request-payload-for-individual-task).
{% endhint %}
{% endtab %}

{% tab title="ASR+Translation+TTS" %}

{% code lineNumbers="true" %}

```json
{
    "pipelineTasks": [
        {
            "taskType": "asr",
            "config": {
                "language": {
                    "sourceLanguage": "xx"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--dddd",
                "audioFormat": "flac",
                "samplingRate": 16000
            }
        },
        {
            "taskType": "translation",
            "config": {
                "language": {
                    "sourceLanguage": "xx",
                    "targetLanguage": "yy"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--fwsd"
            }
        },
        {
            "taskType": "tts",
            "config": {
                "language": {
                    "sourceLanguage": "yy"
                },
                "serviceId": "xxxxx--ssssss-d-ddd--fvdfg",
                "gender": "female"
            }
        }
    ],
    "inputData": {
        "input": [
            {
                "source": null
            }
        ],
        "audio": [
            {
                "audioContent": "{{generated_base64_content}}"
            }
        ]
    }
}
```

{% endcode %}

### Parameter: `pipelineTasks`

**Type:** Array\
\
This parameter takes an array of tasks, in the form of dictionary of **`taskType`** and **`config`**, that are to be done by the integrator.\
In the above example, **`pipelineTasks`** takes two dictionaries:

* Line 3 to 13 i.e., **`ASR Dictionary`**
* Line 14 to 23 i.e., **`Translation Dictionary`**
* Line 24 to 33 i.e., **`TTS Dictionary`**

because integrator wants to do **`ASR`** of the voice input, then **`Translation`** of a digital text followed by **`TTS`**.

**`Line Number 7`** and **`Line Number 18`** are connected and **`Line Number 19`** and **`Line Number 28`** with below understanding. Consider a use-case described below:

Integrator wants to **speak** in say **`Hindi`** language and wants to **hear** the **translated output** in **`Marathi`**. For this to happen, integrator has to:

* Convert the Audio integrator has spoken to digital text i.e., ASR of Hindi
* Translate this digital Hindi text to Marathi digital text i.e., Translation from Hindi to Marathi
* Generate this Marathi text speech i.e., TTS of the Marathi digital text.

{% hint style="info" %}
Therefore, the **language code** for **`ASR`** that is to be inserted in **Line 7**, shall be **`hi`**, i.e., [ISO 639 series](/bhashini-apis/overall-understanding-of-the-api-calls.md) code for Hindi. Once this Hindi digital text is generated, the same shall be translated to Marathi, therefore the **source language code** for **`Translation`** that is to be inserted in **Line 18**, shall also be **`hi`**, which means that **language code** in **Line 7** and **Line 18** shall be same. 

The **target language code** to be inserted in **Line 19** shall be **`mr`**, i.e., [ISO 639 series](/bhashini-apis/overall-understanding-of-the-api-calls.md) code for Marathi.

Speech shall be generated in Marathi which means the language code to be inserted in **Line 28** shall be **`mr`**, same as **Line 19.** 
{% endhint %}

{% hint style="info" %}
Understanding of all other parameters remains same as described above in [**`Request Payload for Individual Task`**](https://bhashini.gitbook.io/bhashini-apis/)[.](#request-payload-for-individual-task)
{% endhint %}
{% endtab %}
{% endtabs %}

## Pre-Processors and Post-Processors within Compute Request

{% tabs %}
{% tab title="ASR" %}
In Automatic Speech Recognition (ASR) systems, preprocessors and postprocessors play a crucial role in refining the audio input and enhancing the textual output, respectively. Below, we provide details on the available preprocessors and postprocessors, along with an example of how to configure them in your request body.

**Preprocessors**

**Voice Activity Detection (VAD)**

* **Syntax:** `"preProcessors": ["vad"]`
* **Function:** VAD allows audio content longer than 30 seconds to be passed and processed. It helps identify voice activity to ensure that only the detected voice activity is processed, reducing the load and improving the efficiency of the ASR system.

**Denoiser**

* **Syntax:** `"preProcessors": ["denoiser"]`
* **Function:** Denoiser helps in improving the accuracy of speech recognition by reducing background noise from audio inputs.

**Postprocessors**

**Hotwords**

* **Syntax:** `"postProcessors": [{"hotword_list":["`पत्रिका`"]}]`
* **Function:** A hotword is postprocessor allows users to share a list of keyword or phrase in which the system is trained to recognize with higher priority or accuracy. This helps in enhancing the ASR performance. This feature is only applicable for Hindi and for service Id "bhashini/ai4bharat/conformer-multilingual-asr".

       **Example:**  a Hindi news broadcast where words like "पत्रिका" (Magazine) are frequently mentioned. Adding these as hotwords ensures they are transcribed correctly rather than being replaced by phonetically similar but incorrect words

 **Inverse Text Normalization (ITN)**

* **Syntax:** `"postProcessors": ["itn"]`
* **Function:** ITN converts spoken numbers and dates into their written forms. For example, the ASR would output "two thousand and twenty three" as "2023".

**Punctuation**

* **Syntax:** `"postProcessors": ["punctuation"]`
* **Function:** This postprocessor adds punctuations to the ASR output, making the text more readable and closer to natural written language.

  **Example:**

  * ASR Output: "hello how are you"
  * Punctuation Output: "Hello, how are you?"

The configuration of preprocessors and postprocessors can be included within the `config` section of the request body as shown below:

{% code lineNumbers="true" %}

```json
"config": {
    "language": {
        "sourceLanguage": "xx"
    },
    "serviceId": "xxxxx--ssssss-d-ddd--dddd",
    "audioFormat": "flac",
    "samplingRate": 16000,
    "preProcessors": ["vad"],
    "postProcessors": [{
                    "hotword_list": ["पत्रिका", "रंगकर्म", "फिक्र"]
                }, "itn", "punctuation"]
}
```

{% endcode %}
{% endtab %}

{% tab title="Translation" %}
In translation (NMT) systems, postprocessors play a crucial role in refining the textual output to meet specific needs. Below, we provide details on the postprocessor available for translation, along with an example of how to configure it in your request body.

**Postprocessors**

**Glossary**

* **Syntax:** `"postProcessors": ["glossary"]`
* **Function:** The glossary postprocessor allows users to create a list of glossary terms within Bhashini Udyat under the My Profile Section once logged in. Glossary terms created are unique for each Bhashini Inference API Key generated under app names. This postprocessor ensures that specific nouns and noun phrases have their translations overridden as per the user's glossary.

**Example:**

* Default Translation: "Digital India Bhashini Division" is translated to "डिजिटल इंडिया भैसिनी प्रभाग".
* With Glossary Term: If the glossary term between English and Hindi is entered as "डिजिटल इंडिया भाषिणी डिवीज़न", this will override the default translation.

**Link to Access My Profile Page and Generate Keys and Glossary:** [Bhashini Udyat Profile Page](https://bhashini.gov.in/ulca/profile)

**Glossary Terms Usage:** Glossary terms help provide customized solutions for domain-specific translations, ensuring accuracy and context relevance in the translated output.

**Example of Glossary Usage:**

* Case sensitivity handling (Ex: Glossary entry - English to  Hindi as IPO -> आईपीओ). 
* Glossary entries will work by default for:
  1. Entered noun/noun phrase (e.g., IPO)
  2. Capitalized case (Ipo)
  3. Lower case (ipo)
  4. Upper case ( IPO)
  5. Reverse case (if आईपीओ is the source, the target is IPO when translating from Hindi to English).

#### Configuration Example

The configuration of the glossary postprocessor can be included within the `config` section of the request body as shown below:

{% code lineNumbers="true" %}

```json
"config": {
    "language": {
        "sourceLanguage": "hi",
        "targetLanguage": "xx"
    },
    "postProcessors": ["glossary"]
    "serviceId": "xxxxx--ssssss-d-ddd--dddd"
}
```

{% endcode %}
{% endtab %}

{% tab title="TTS" %}
In Text to Speech (TTS) systems, preprocessor, postprocessors play a crucial role in refining the audio output and enhancing the audio quality respectively. Below, we have provide details on the available preprocessor, postprocessors, along with an format of how to configure them in your request body.

**Preprocessors**

**Text Normalization (TN)**

* **Syntax:** `"preProcessors": ["text-normalization"]`
* **Function:** It converts numbers and dates into their name forms. For example, the TTS would output "2025" as "two thousand twenty five".

**Postprocessors**

**High Compression**

* **Syntax:** `"postProcessors": ["high-compression"]`
* **Function:** This helps minimize audio file size during download without compromising quality, making it suitable for low-bandwidth(network) environment and applications where storage is a primary concern It also speeds up transmission and playback by reducing latency. It gives 64kbps audio.

**Low Compression**

* **Syntax:** `"postProcessors": ["low-compression"]`
* **Function:** This helps minimize audio file size during download without a significant loss in audio quality, making it suitable for low-bandwidth(network) environments. It also speeds up transmission and playback by reducing latency. It gives 128kbps audio.
  {% endtab %}
  {% endtabs %}