> 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/settings/general/voice-api.md).

# Voice API

Where you manage Voice API credits, usage, and credentials. For the endpoints themselves — TTS, ASR, supported languages, and request formats — see the [Voice API developer reference](/docs/developers/apis/voice-api.md).

Go to **Settings → Workspace → Voice API**.

{% hint style="warning" %}
Viewing the **Billing** tab requires the **View billing** permission. Buying credits or changing auto top-up settings requires **Manage plan & billing**. Without **View billing**, the page opens on **Detailed usage** instead of **Billing**.
{% endhint %}

The page has three tabs, each documented below:

| Tab                               | Description                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [Billing](#billing)               | Voice credit balance, usage this period, buying credits, and auto top-up.                                    |
| [Detailed usage](#detailed-usage) | Text-to-speech and speech recognition usage over a custom date range, with filters and segmentation.         |
| [Deployment](#deployment)         | Teamspace credentials and a request builder for calling the [Voice API](/docs/developers/apis/voice-api.md). |

***

## Billing

### Usage this period

A card showing **Text-to-speech** and **Speech recognition** request counts for **This month** or **Last month**, plus a daily usage chart for the selected month.

### Voice credit balance

Your remaining Voice API credits. One credit equals one TTS or ASR request.

{% hint style="warning" %}
If the balance drops below the auto top-up threshold, a **Low credit balance** notice appears at the top of the tab with a **Buy credits** shortcut.
{% endhint %}

### Buy credits

| Field  | Description                                                                  |
| ------ | ---------------------------------------------------------------------------- |
| Amount | 100–10,000 credits, in steps of 50. Set with the slider or the number field. |
| Price  | $0.05 per credit; the total price updates as you adjust the amount.          |

Select **Buy credits** to complete the purchase through Stripe Checkout. After checkout you're returned to this tab with a confirmation ("Payment successful...") or cancellation ("Checkout canceled...") message.

### Credit auto top-up

Automatically buys 100 credits at $0.05 each when your balance falls below a threshold you set.

| Field                                       | Description                                                                                                                                                    |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable auto top-up of credits               | Turns automatic top-up on or off. Requires a payment method already on file — enabling it without one shows an error asking you to add a payment method first. |
| Top up when balance falls below *n* credits | The balance threshold that triggers an automatic top-up. Must be 1 or higher.                                                                                  |

If the last automatic top-up payment failed, an **Auto top-up payment failed** notice appears with two actions:

| Action                | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| Update payment method | Opens the Stripe billing portal to change the card on file.                   |
| Retry                 | Retries the failed top-up on the same charge, rather than creating a new one. |

### Manage billing and invoices

Two buttons at the bottom of the tab open the Stripe billing portal: **Manage billing** for your subscription and payment details, and **View invoices** for past invoices.

***

## Detailed usage

A breakdown of Voice API usage over a period you choose.

### Date range

Select the **Date range** chip to set the reporting window. Choose a preset (Last hour, Today, This week, Last week, Month to date, This month, Last month, This quarter, Last quarter, This year, Last year) or set custom **Start date** and **End date** values with the calendars.

### Summary tiles

Four tiles summarise usage for the selected range:

| Tile                      | What it shows                        |
| ------------------------- | ------------------------------------ |
| Text-to-speech            | Number of TTS requests.              |
| Speech generation time    | Total audio time generated by TTS.   |
| Speech-to-text            | Number of ASR requests.              |
| Speech transcription time | Total audio time transcribed by ASR. |

### Credit usage

A chart of credit usage over the selected range. Use the controls to shape it:

| Control      | Options                           |
| ------------ | --------------------------------- |
| Group by     | Time granularity — e.g. Day.      |
| Segment by   | Dimension to split the chart by.  |
| Request type | Filter to specific request types. |
| Teamspace    | Filter to specific teamspaces.    |
| Language     | Filter to specific languages.     |

Select **Reset all** to clear the controls. Use the download icons to export the data as CSV or save the chart as an image. When there's no matching data, the chart shows **No data to display**.

***

## Deployment

Credentials and a request builder for calling the [Voice API](/docs/developers/apis/voice-api.md) directly.

### Credentials

| Field           | Description                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| Teamspace       | Select the teamspace whose credentials to use.                                                                  |
| Teamspace ID    | The `{teamspace_id}` path parameter for API requests. Select the copy icon to copy it.                          |
| Takeover secret | The bearer token for the `Authorization` header. Select the eye icon to reveal it, or the copy icon to copy it. |

### Request builder

Build and copy a sample request. Toggle between **Text to speech** and **Speech to text** to switch the request type.

{% tabs %}
{% tab title="Text to speech" %}

| Field        | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| Language     | The language of the generated speech.                            |
| Gender       | Voice gender — Male or Female (availability varies by language). |
| Format       | Output audio format, e.g. `opus`.                                |
| Speed        | Playback speed, adjustable with the slider.                      |
| {% endtab %} |                                                                  |

{% tab title="Speech to text" %}

| Field    | Description                                     |
| -------- | ----------------------------------------------- |
| Language | The language spoken in the audio to transcribe. |

Send an audio file (MP3 or WAV, max 15 MB) as multipart form data — the generated command uses `-F "file=@audio.mp3"`.
{% endtab %}
{% endtabs %}

The builder generates a live **cURL** command reflecting your selections, with the teamspace's takeover secret pre-filled — select the copy icon to copy it. Select **Voice API documentation** to open the full [developer reference](/docs/developers/apis/voice-api.md).

***

## Related

{% content-ref url="/pages/gmEWLdGoIEfZL2z7YMZ9" %}
[Voice API](/docs/developers/apis/voice-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/Qtek4zmVwy0RDwPm7xsx" %}
[Plan & billing](/docs/settings/general/plan-and-billing.md)
{% endcontent-ref %}