> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/developers/apis/voice-api.md).

# Voice API

The Voice API provides two services: **Text-to-Speech (TTS)**, which converts text into spoken audio, and **Automatic Speech Recognition (ASR)**, which transcribes audio into text.

Common languages are powered by a general large language model. Local languages — including Kinyarwanda, Kuanyama, Filipino, and Cebuano — are powered by fine-tuned models trained on data collected from native speakers, by Proto and through its partners. These are tailored for citizen engagement, consumer protection, and anti-scam support.

{% hint style="info" %}
Gender availability varies by language. See [Local languages](#local-languages) and [All supported languages](#all-supported-languages) for the options per language.
{% endhint %}

***

## Setting up your account

The Voice API is available to all Proto accounts. No additional setup is required beyond having a workspace.

Each successfully processed TTS or ASR request consumes **one interaction**. Usage is tracked against your workspace — see [Plan & billing](/docs/settings/general/plan-and-billing.md) for current rates.

***

## Authentication

Every request must include your teamspace takeover secret as a bearer token in the `Authorization` header.

{% code title="Authorization header" overflow="wrap" %}

```
Authorization: Bearer <teamspace_takeover_secret>
```

{% endcode %}

To find your credentials:

{% stepper %}
{% step %}

### Open teamspace settings

Go to **Settings → Workspace →** [**Teamspaces**](/docs/settings/teamspaces.md) and select the teamspace you want to use.
{% endstep %}

{% step %}

### Copy the values

Copy the **Takeover secret** for the bearer token, and the **Teamspace ID** (shown directly above it) for the `{teamspace_id}` path parameter.
{% endstep %}
{% endstepper %}

***

## Local languages

Supported by fine-tuned models trained on data collected from native speakers, optimised for citizen engagement, consumer protection, and anti-scam support.

| Language    | Code  | ASR | TTS — Male | TTS — Female |
| ----------- | ----- | --- | ---------- | ------------ |
| Kinyarwanda | `rw`  | ✓   | —          | ✓            |
| Kuanyama    | `kj`  | ✓   | —          | ✓            |
| Filipino    | `tl`  | ✓   | ✓          | ✓            |
| Cebuano     | `ceb` | ✓   | ✓          | ✓            |

***

## All supported languages

Common languages are powered by a general large language model. Every language below supports ASR, plus both male and female TTS voices.

<details>

<summary>View all 95 supported languages</summary>

| Language              | Code      | ASR | TTS — Male | TTS — Female |
| --------------------- | --------- | --- | ---------- | ------------ |
| Afrikaans             | `af`      | ✓   | ✓          | ✓            |
| Amharic               | `am`      | ✓   | ✓          | ✓            |
| Arabic                | `ar`      | ✓   | ✓          | ✓            |
| Assamese              | `as`      | ✓   | ✓          | ✓            |
| Azerbaijani           | `az`      | ✓   | ✓          | ✓            |
| Belarusian            | `be`      | ✓   | ✓          | ✓            |
| Bemba                 | `bem`     | ✓   | ✓          | ✓            |
| Bulgarian             | `bg`      | ✓   | ✓          | ✓            |
| Bengali               | `bn`      | ✓   | ✓          | ✓            |
| Tibetan               | `bo`      | ✓   | ✓          | ✓            |
| Bosnian               | `bs`      | ✓   | ✓          | ✓            |
| Catalan               | `ca`      | ✓   | ✓          | ✓            |
| Czech                 | `cs`      | ✓   | ✓          | ✓            |
| Welsh                 | `cy`      | ✓   | ✓          | ✓            |
| Danish                | `da`      | ✓   | ✓          | ✓            |
| German                | `de`      | ✓   | ✓          | ✓            |
| Greek                 | `el`      | ✓   | ✓          | ✓            |
| English               | `en`      | ✓   | ✓          | ✓            |
| Spanish               | `es`      | ✓   | ✓          | ✓            |
| Estonian              | `et`      | ✓   | ✓          | ✓            |
| Basque                | `eu`      | ✓   | ✓          | ✓            |
| Persian               | `fa`      | ✓   | ✓          | ✓            |
| Finnish               | `fi`      | ✓   | ✓          | ✓            |
| French                | `fr`      | ✓   | ✓          | ✓            |
| Galician              | `gl`      | ✓   | ✓          | ✓            |
| Gujarati              | `gu`      | ✓   | ✓          | ✓            |
| Hausa                 | `ha`      | ✓   | ✓          | ✓            |
| Hawaiian              | `haw`     | ✓   | ✓          | ✓            |
| Hebrew                | `he`      | ✓   | ✓          | ✓            |
| Hindi                 | `hi`      | ✓   | ✓          | ✓            |
| Croatian              | `hr`      | ✓   | ✓          | ✓            |
| Haitian Creole        | `ht`      | ✓   | ✓          | ✓            |
| Hungarian             | `hu`      | ✓   | ✓          | ✓            |
| Armenian              | `hy`      | ✓   | ✓          | ✓            |
| Indonesian            | `id`      | ✓   | ✓          | ✓            |
| Icelandic             | `is`      | ✓   | ✓          | ✓            |
| Italian               | `it`      | ✓   | ✓          | ✓            |
| Japanese              | `ja`      | ✓   | ✓          | ✓            |
| Georgian              | `ka`      | ✓   | ✓          | ✓            |
| Kazakh                | `kk`      | ✓   | ✓          | ✓            |
| Khmer                 | `km`      | ✓   | ✓          | ✓            |
| Kannada               | `kn`      | ✓   | ✓          | ✓            |
| Korean                | `ko`      | ✓   | ✓          | ✓            |
| Latin                 | `la`      | ✓   | ✓          | ✓            |
| Luxembourgish         | `lb`      | ✓   | ✓          | ✓            |
| Lao                   | `lo`      | ✓   | ✓          | ✓            |
| Lithuanian            | `lt`      | ✓   | ✓          | ✓            |
| Latvian               | `lv`      | ✓   | ✓          | ✓            |
| Malagasy              | `mg`      | ✓   | ✓          | ✓            |
| Māori                 | `mi`      | ✓   | ✓          | ✓            |
| Macedonian            | `mk`      | ✓   | ✓          | ✓            |
| Malayalam             | `ml`      | ✓   | ✓          | ✓            |
| Mongolian             | `mn`      | ✓   | ✓          | ✓            |
| Marathi               | `mr`      | ✓   | ✓          | ✓            |
| Malay                 | `ms`      | ✓   | ✓          | ✓            |
| Maltese               | `mt`      | ✓   | ✓          | ✓            |
| Burmese               | `my`      | ✓   | ✓          | ✓            |
| Nepali                | `ne`      | ✓   | ✓          | ✓            |
| Dutch                 | `nl`      | ✓   | ✓          | ✓            |
| Norwegian             | `no`      | ✓   | ✓          | ✓            |
| Chichewa              | `ny`      | ✓   | ✓          | ✓            |
| Punjabi               | `pa`      | ✓   | ✓          | ✓            |
| Polish                | `pl`      | ✓   | ✓          | ✓            |
| Pashto                | `ps`      | ✓   | ✓          | ✓            |
| Portuguese            | `pt`      | ✓   | ✓          | ✓            |
| Romanian              | `ro`      | ✓   | ✓          | ✓            |
| Russian               | `ru`      | ✓   | ✓          | ✓            |
| Sindhi                | `sd`      | ✓   | ✓          | ✓            |
| Sinhala               | `si`      | ✓   | ✓          | ✓            |
| Slovak                | `sk`      | ✓   | ✓          | ✓            |
| Slovenian             | `sl`      | ✓   | ✓          | ✓            |
| Shona                 | `sn`      | ✓   | ✓          | ✓            |
| Somali                | `so`      | ✓   | ✓          | ✓            |
| Albanian              | `sq`      | ✓   | ✓          | ✓            |
| Serbian               | `sr`      | ✓   | ✓          | ✓            |
| Sundanese             | `su`      | ✓   | ✓          | ✓            |
| Swedish               | `sv`      | ✓   | ✓          | ✓            |
| Swahili               | `sw`      | ✓   | ✓          | ✓            |
| Tamil                 | `ta`      | ✓   | ✓          | ✓            |
| Telugu                | `te`      | ✓   | ✓          | ✓            |
| Tajik                 | `tg`      | ✓   | ✓          | ✓            |
| Thai                  | `th`      | ✓   | ✓          | ✓            |
| Turkmen               | `tk`      | ✓   | ✓          | ✓            |
| Tongan                | `ton`     | ✓   | ✓          | ✓            |
| Turkish               | `tr`      | ✓   | ✓          | ✓            |
| Tatar                 | `tt`      | ✓   | ✓          | ✓            |
| Twi                   | `tw`      | ✓   | ✓          | ✓            |
| Ukrainian             | `uk`      | ✓   | ✓          | ✓            |
| Urdu                  | `ur`      | ✓   | ✓          | ✓            |
| Uzbek                 | `uz`      | ✓   | ✓          | ✓            |
| Vietnamese            | `vi`      | ✓   | ✓          | ✓            |
| Yiddish               | `yi`      | ✓   | ✓          | ✓            |
| Yoruba                | `yo`      | ✓   | ✓          | ✓            |
| Chinese (Simplified)  | `zh-Hans` | ✓   | ✓          | ✓            |
| Chinese (Traditional) | `zh-Hant` | ✓   | ✓          | ✓            |

</details>

***

## Text-to-Speech (TTS)

Convert text into spoken audio.

{% code title="Endpoint" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/voice/{teamspace_id}/tts
```

{% endcode %}

**Headers**

```
Authorization: Bearer <teamspace_takeover_secret>
Content-Type: application/json
```

**Request body**

```json
{
  "text": "string",
  "lang": "en",
  "response_format": "mp3 | wav",
  "speed": 1.0,
  "gender": "female"
}
```

| Parameter         | Required | Description                                                        |
| ----------------- | -------- | ------------------------------------------------------------------ |
| `text`            | Yes      | The text to convert to speech. Maximum 5,000 characters.           |
| `lang`            | No       | Language code. Defaults to `en`. See the language tables above.    |
| `response_format` | No       | Output format: `mp3` or `wav`. Defaults to `mp3`.                  |
| `speed`           | No       | Playback speed, 0.25–4.0. Defaults to 1.0.                         |
| `gender`          | No       | Voice gender: `male` or `female`. Availability varies by language. |

**Example request**

{% code title="cURL" overflow="wrap" %}

```bash
curl -X POST "https://v3-api.proto.cx/api/platform/v1/voice/{teamspace_id}/tts" \
  -H "Authorization: Bearer <teamspace_takeover_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Muraho neza",
    "lang": "rw",
    "response_format": "mp3",
    "speed": 1.0,
    "gender": "female"
  }'
```

{% endcode %}

**Response**

The API returns a **Base64-encoded audio payload** — not a downloadable file. Decode it client-side before playing or saving.

{% hint style="warning" %}
The response is a raw Base64 string. You must decode it to bytes and write those bytes to a `.mp3` or `.wav` file.
{% endhint %}

<details>

<summary>Decode the response to an audio file</summary>

Copy the Base64 response string into a file, e.g. input.txt.Run:$b64 = Get-Content input.txt -Raw$b64 = $b64 -replace '\s',''\[IO.File]::WriteAllBytes("output.mp3", \[Convert]::FromBase64String($b64))This generates output.mp3 in the same directory.With the Base64 response saved to input.txt:base64 --decode input.txt > output.mp3import base64with open("input.txt") as f:    data = f.read()with open("output.mp3", "wb") as out:    out.write(base64.b64decode(data))

</details>

***

## Speech Recognition (ASR)

Convert spoken audio into text.

{% code title="Endpoint" overflow="wrap" %}

```
POST https://v3-api.proto.cx/api/platform/v1/voice/{teamspace_id}/asr
```

{% endcode %}

**Headers**

```
Authorization: Bearer <teamspace_takeover_secret>
Content-Type: multipart/form-data
```

**Request body**

| Parameter | Required | Description                                          |
| --------- | -------- | ---------------------------------------------------- |
| `file`    | Yes      | The audio file to transcribe. mp3 or wav, max 15 MB. |
| `lang`    | Yes      | Language code                                        |

**Example request**

{% code title="cURL" overflow="wrap" %}

```bash
curl -X POST "https://v3-api.proto.cx/api/platform/v1/voice/{teamspace_id}/asr" \
  -H "Authorization: Bearer <teamspace_takeover_secret>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.mp3" \
  -F "lang='en'"
```

{% endcode %}

**Response**

The API returns the **transcribed text** extracted from the audio file.

***

## Related

{% content-ref url="/pages/isn9npKNcj2GVUDY1avs" %}
[APIs](/docs/developers/apis.md)
{% endcontent-ref %}

{% content-ref url="/pages/fMIFSqvq7stuR5GeAUIn" %}
[Local languages](/docs/developers/local-languages.md)
{% endcontent-ref %}