> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Text-to-Speech
> Deprecated: Convert text to natural-sounding speech with customizable voice settings, allowing you to generate audio files for playback in your applications.
The asynchronous `POST /tts` flow is deprecated. If you’re starting a new integration, use `POST /tts-stream` instead—you receive audio as it’s generated, without juggling task status, run IDs, and separate download calls.
This endpoint transforms your written text into remarkably natural speech, opening up possibilities for narration, accessibility features, and interactive experiences in your applications. When you provide text along with voice preferences, our Model creates an audio file that captures the nuances and natural flow of human speech.
## Personalizing Your Voice
### Voice Personalization Options
You can shape the character of your generated voice by specifying these key attributes:
* **Gender**: Select the voice gender with a simple numeric code:
* **Age**: Add in the voice age to reflect the intended audience or context.
### Selecting Your Voice
Our platform offers two approaches to finding the perfect voice:
* **Choose from our voice library:** Browse our collection of ready-to-use voices through the [`/list-voices`](list-voices) endpoint to find the perfect match for your project.
* **Use your signature voice:** Utilize the [`/create-custom-voice`](create-custom-voice) endpoint to clone an audio recording containing your signature voice.
### Language Support
Our technology supports numerous languages and dialects for global reach. To see what's available:
* Check the [`/source-languages`](get-source-languages) or [`/target-languages`](get-target-languages) endpoints for a complete list of supported languages with their corresponding IDs.
## How the Process Works
This endpoint uses an asynchronous workflow, which means your application can keep doing other things while the speech is being generated. Here's how it works, step-by-step:
Start by sending in your text, along with voice preferences such as language, age, and gender. You can also specify a voice from our library or a custom voice you've created.
Once your request is received, our system instantly returns a unique `task_id`. This lets you check back later to see how things are going—just like tracking a package.
Use your `task_id` to check the current status of your request by calling the [`/tts/{task_id}`](get-tts-result) endpoint. You’ll know whether your audio is still being generated, completed, or if something went wrong.
When your task is marked as complete (`SUCCESS`), you'll get a `run_id`. Use this ID to download your final audio file from the [`/tts-result/{run_id}`](get-tts-result) endpoint.
This approach works particularly well for longer passages or when processing multiple requests simultaneously.
## Example: Creating Your First Audio
Here's a practical example showing how to generate speech about Mars:
```python [expandable] theme={null}
import requests
import time
# Define the text and voice characteristics
tts_payload = {
"text": "Mars, the red planet, captivates our imagination with its rusty landscape, ancient river valleys, and massive polar ice caps. Its thin atmosphere whispers of a warmer, wetter past that scientists are eager to understand.",
"voice_id": 147320, # Replace with your chosen voice ID
"language": 1, # English
"gender": 1, # Male voice
"age": 30 # Adult voice characteristic
}
# Set up your API credentials
headers = {
"x-api-key": "your-api-key", # Replace with your actual API key
"Content-Type": "application/json"
}
# Step 1: Submit your text-to-speech request
response = requests.post(
"https://client.camb.ai/apis/tts",
json=tts_payload,
headers=headers
)
# Check if the request was successful
response.raise_for_status()
task_data = response.json()
task_id = task_data["task_id"]
print(f"Speech task created! Task ID: {task_id}")
# Step 2: Check progress until complete
while True:
status_response = requests.get(
f"https://client.camb.ai/apis/tts/{task_id}",
headers=headers
)
status_data = status_response.json()
status = status_data["status"]
print(f"Status: {status}")
if status == "SUCCESS":
run_id = status_data["run_id"]
break
elif status == "FAILED":
print("Task failed!")
break
# Wait before checking again
time.sleep(2)
# Step 3: Download your audio file
if status == "SUCCESS":
print(f"Speech ready! Run ID: {run_id}")
audio_response = requests.get(
f"https://client.camb.ai/apis/tts-result/{run_id}",
headers=headers,
stream=True
)
# Save the audio file
with open("speech.wav", "wb") as audio_file:
for chunk in audio_response.iter_content(chunk_size=1024):
if chunk:
audio_file.write(chunk)
print("✨ Generated speech was saved as 'speech.wav'")
```
With this approach, you can create engaging audio content that brings your text to life while your application continues performing other tasks during processing.
## OpenAPI
````yaml post /tts
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://client.camb.ai/apis
security: []
paths:
/tts:
post:
tags:
- APIs
- Text-to-Speech
summary: Create TTS (Deprecated)
description: >-
Deprecated. For new integrations, use `POST /tts-stream` for streaming
text-to-speech.
operationId: create_tts_tts_post
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTTSRequestPayload'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskID'
description: >-
A JSON that contains the unique identifier for the task. This
is used to query the status of the story task that is running.
It is returned when a create request is made for a
text-to-speech.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
deprecated: true
security:
- APIKeyHeader: []
components:
schemas:
CreateTTSRequestPayload:
allOf:
- $ref: '#/components/schemas/CreateTaskWithNameAndDescription'
- properties:
text:
type: string
title: Text
description: The text to be converted to speech
voice_id:
type: integer
title: Voice Id
description: The voice ID to be used to generate speech.
default: 147320
language:
$ref: '#/components/schemas/SourceLanguages'
description: The language in which the provided text is written in.
gender:
anyOf:
- $ref: '#/components/schemas/Gender'
default: 1
age:
title: Age
description: The age of the speaker of in the speech to be generated.
type: object
required:
- text
- voice_id
- language
title: CreateTTSRequestPayload
TaskID:
properties:
task_id:
type: string
title: Task ID
type: object
title: Task ID
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
CreateTaskWithNameAndDescription:
properties:
project_name:
type: string
title: Project Name
description: >-
Enter a distinctive name for your project that reflects its purpose
or content. This name will be displayed in your CAMB.AI workspace
dashboard and used to organize related assets, transcriptions, etc..
. Choose something memorable that helps you quickly identify this
specific project among your other voice, audio and localization
tasks.
minLength: 3
maxLength: 255
nullable: true
project_description:
type: string
title: Project Description
description: >-
Provide details about your project's goals and specifications.
Include information such as the target languages for translation or
dubbing, desired voice characteristics, emotional tones to capture,
or specific audio processing requirements, outlining the workflow
here can serve as valuable documentation for organizational
purposes.
minLength: 3
maxLength: 5000
nullable: true
SourceLanguages:
type: integer
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
- 70
- 71
- 73
- 74
- 75
- 76
- 78
- 79
- 80
- 81
- 82
- 83
- 84
- 85
- 86
- 87
- 88
- 90
- 91
- 92
- 93
- 94
- 95
- 96
- 97
- 98
- 99
- 100
- 101
- 102
- 103
- 104
- 106
- 107
- 108
- 109
- 110
- 111
- 112
- 113
- 114
- 115
- 116
- 117
- 118
- 119
- 120
- 121
- 122
- 123
- 124
- 125
- 126
- 127
- 128
- 129
- 130
- 131
- 132
- 133
- 134
- 135
- 136
- 139
- 140
- 141
- 142
- 143
- 144
- 145
- 146
- 148
default: 1
Gender:
type: integer
enum:
- 0
- 1
- 2
- 9
title: Gender
description: The gender of the speaker.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
description: >-
The `x-api-key` is a custom header required for authenticating requests
to our API. Include this header in your request with the appropriate API
key value to securely access our endpoints. You can find your API key(s)
in the 'API' section of our studio website.
````