> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wav.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Text To Speech
> Synthesize speech from text with voice and gender customization, plus optional webhook callback.
Give priority to the sample audio first, then to the voice ID, and lastly to gender.
Convert any given text into realistic speech using your chosen voice and gender.
**TextToSpeech** enables you to instantly bring written content to life. Perfect for:
* Creating dynamic audio narrations or voiceovers
* Choosing gender-specific voice stylings for different contexts
* Using webhooks for real-time integration with your workflows
***
## Endpoint
```http theme={null}
POST /v1/TextToSpeech
```
Use this endpoint to initiate a new text-to-speech audio generation.
***
## Sample Output
Prompt: When I think of superheroes I think of super humans. I think of Superman, Wolverine and Wonder Woman. Usually they have a cape, or a mask to hide their face just in case. They have X-ray vision and super-human strength. Some can even breathe in outer space. They fly around a while, but always come back to keep our cities safe. They’re here to save humanity from itself. It’s a metaphor for how we look outside ourselves for help, and while the fantasies are fun, I choose to look for me and you.
Download Audio
***
## Try it Yourself
Visit the [TextToSpeech Endpoint Explorer](/api-documentation/endpoint/TextToSpeech) to try your own text samples.
***
## Request Parameters
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------- |
| `text` | String | Yes | The text content to convert to speech |
| `voice_id` | String | Optional | Voice ID of the artist. Visit [Get Voices by Name](/api-documentation/endpoint/searchVoices) to get voice\_id. |
| `sample_audio_url` | String | Optional | URL of Voice you want. |
| `gender` | String | Yes | Gender of the voice ("male", "female") |
| `webhook_url` | String | No | URL to receive a callback with generated audio |
> **content-type:** application/json
***
## Sample Request
### Python
```python theme={null}
import requests
url = "https://api.wav.com/api/public/v1/TextToSpeech"
headers = {
"Authorization": "",
"Content-Type": "application/json"
}
payload = {
"text": "Welcome to WAV! This is a sample text-to-speech generation.",
"sample_audio_url": "",
"voice_id": "e1cb7380-e3db-433a-b186-a996d7545986",
"gender": "female",
"webhook_url": "https://example.com/my-webhook"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
***
## Sample Response
### Success (200 OK)
```json theme={null}
{
"success":true,
"task_id":"0a65cbb6-2ab8-4949-9ee0-0e8c138ac2cf",
"conversion_id":"6542baa6-d61f-4d90-b832-ed929d9c0996",
"eta":17,
"credit_estimate":0.68,
"message":"",
"status":"IN_QUEUE"
}
```
***
## Webhook Response
Once audio is ready, your webhook will receive:
```json theme={null}
{
"success": true,
"conversion_type": "Text To Speech",
"task_id": "037a9a09-3fc6-4a90-8748-d3406ff712eb",
"conversion_id": "f1970224-ab06-4aa6-a832-0f3fd23212b7",
"conversion_path": "https://cdn1.wav.com/conversions/api/tts/195e5815-b871-4ea0-86a2-7f5eb1c696d2/195e5815-b871-4ea0-86a2-7f5eb1c696d2.mp3",
"message": "Conversion Completed",
"conversion_cost": "0.68",
"conversion_duration": 27.78
}
```
***
## Error Codes
* **402 Payment Required**: Not enough credits to process the request
* **422 Unprocessable Entity**: Invalid or missing fields
* **500 Internal Server Error**: Server-side failure during processing
***
## Payload and Request Formation
## OpenAPI
````yaml POST /v1/TextToSpeech
openapi: 3.1.0
info:
title: WAV API
version: 1.0.0
description: API for retrieving conversion details by ID.
servers:
- url: https://api.wav.com/api/public
description: Production server
security: []
paths:
/v1/TextToSpeech:
post:
summary: Convert text to speech using a specified voice
description: >-
Synthesize speech from text with voice and gender customization, plus
optional webhook callback.
Give priority to the sample audio first, then to the voice ID, and
lastly to gender.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: Text to convert to speech
example: Hello, this is a sample text to speech conversion.
voice_id:
type: string
description: Voice model ID
example: e1cb7380-e3db-433a-b186-a996d7545986
gender:
type: string
description: Gender preference for the voice (e.g., "male", "female")
example: female
sample_audio_url:
type: string
description: >-
An audio URL containing a voice sample of the target speaker
without music or overlapping voices. Recommended over
voice_id for better output quality.
example:
webhook_url:
type: string
description: Callback URL for async processing
example: https://example.com/my-webhook
required:
- text
anyOf:
- required:
- sample_audio_url
- required:
- voice_id
responses:
'200':
description: Successfully initiated task
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
task_id:
type: string
conversion_id:
type: string
eta:
type: integer
description: Estimated processing time in seconds
credit_estimate:
type: number
format: float
message:
type: string
status:
type: string
example:
success: true
task_id: 0a65cbb6-2ab8-4949-9ee0-0e8c138ac2cf
conversion_id: 6542baa6-d61f-4d90-b832-ed929d9c0996
eta: 17
credit_estimate: 0.68
message: ''
status: IN_QUEUE
'402':
description: Payment Required
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Insufficient credit balance
'422':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Missing required field: text'
'500':
description: Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Internal Server Error
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````