Skip to main content
POST
/
tts
Create Tts
curl --request POST \
  --url https://client.camb.ai/apis/tts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "<string>",
  "voice_id": 123,
  "language": 1,
  "project_name": "<string>",
  "project_description": "<string>",
  "folder_id": 2,
  "gender": 1,
  "age": "<unknown>"
}
'
{
  "task_id": "<string>"
}
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 endpoint to find the perfect match for your project.
  • Use your signature voice: Utilize the /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:

​
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:
1

Submit Your Request

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.
2

Receive Your `task_id`

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.
3

Track Progress of Your Speech Generation

Use your task_id to check the current status of your request by calling the /tts/{task_id} endpoint. You’ll know whether your audio is still being generated, completed, or if something went wrong.
4

Retrieve the Final Audio File

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} 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: 
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": 123,    # 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.

Authorizations

​
x-api-key
string
header
required

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.

Body

application/json
​
text
string
required

The text to be converted to speech

​
voice_id
integer
required

The voice ID to be used to generate speech.

​
language
enum<integer>
required

The language in which the provided text is written in.

Available options:
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
​
project_name
string | null

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.

Required string length: 3 - 255
​
project_description
string | null

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.

Required string length: 3 - 5000
​
folder_id
integer | null

Specify the organizational folder within your CAMB.AI workspace where this task should be created and stored. The folder must already exist in your workspace and be accessible through your current API key authentication. This helps maintain project organization by grouping related tasks together, making it easier to manage and locate your projects.

Required range: x >= 1
​
gender
enum<integer>
default:1

The gender of the speaker.

Available options:
0,
1,
2,
9
​
age
any

The age of the speaker of in the speech to be generated.

Response

Successful Response

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.

​
task_id
string