> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/api-reference/core-api-reference/character-crafting-apis/text-to-speech-api.md).

# Text to Speech API

This page explains how to interact with the standalone Text-to-Speech (TTS) API to generate audio from a given transcript, using a selected voice from the available voice list.

{% hint style="danger" %}
This API is available only on the Enterprise Plan.
{% endhint %}

## Generate Audio from Text

<mark style="color:green;">`POST`</mark> `https://api.convai.com/tts/`

***

## **Headers**

| **CONVAI-API\_KEY**<mark style="color:red;">**\***</mark> | String | Your Convai API Key. |
| --------------------------------------------------------- | ------ | -------------------- |
| **Content-Type**<mark style="color:red;">**\***</mark>    | String | application/json     |

***

## Request Body

| Name                                             | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **transcript**<mark style="color:red;">\*</mark> | String | The text to be converted into audio.                                                                                                                                                                                                                                                                                                                                                       |
| **voice**<mark style="color:red;">\*</mark>      | String | <p>Specifies the type of voice used for the audio response. This can be retrieved using the <a href="/api-docs/api-reference/core-api-reference/character-crafting-apis/voice-list-api.md">Voice List API</a>, from the <code>voice\_value</code> attribute of the desired voice.<br><br><strong>NOTE :</strong> Realtime voices are not supported in the standalone TTS API endpoint.</p> |
| filename                                         | String | The name of the audio file.                                                                                                                                                                                                                                                                                                                                                                |
| encoding                                         | String | <p>This is the format of the audio file. We currently support WAV and MP3 formats for STT (speech-to-text) audio. By default, it is set to WAV.<br><br><strong>NOTE :</strong> MP3 is not supported by all voices.</p>                                                                                                                                                                     |

***

## Response

If the API call is successful, it returns the generated audio file as the response.

***

## Sample Code Snippet

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

```python
import requests
import json

url = "https://api.convai.com/tts/"

payload = json.dumps({
  "transcript": "In the quiet of the morning, as the sky turned shades of pink and orange, she walked along the path lined with blooming flowers, feeling the cool breeze on her face. It was finally time for dinner.",
  "voice": "fable_OpenAi_c4d30a32-bcaf-4048-b7b0-0f2bb293205a",
  "encoding": "wav"
})

headers = {
  'CONVAI-API-KEY': '<Your Convai API Key>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

if response.status_code == 200:
    with open('audio.wav','wb') as f:
      f.write(response.content)
else:
    print(response.text)
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/api-reference/core-api-reference/character-crafting-apis/text-to-speech-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.