POST
/
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,
  "gender": 0,
  "age": "<any>"
}'
{
  "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 Personaltiy 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/{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

Response

200
application/json

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.