Camb.ai’s APIs provide developers with the tools to integrate our cutting-edge voiceover and dubbing technology into their applications.

​
Understanding the API

The Camb.ai API is the backbone of our platform, powering both the website and programmatic access. It ensures consistent quality and performance across all interfaces. Here’s what you need to know to get started:

​
API Key

Our journey begins with an API key, which you can obtain from your Camb.ai dashboard. This key is essential for authenticating your requests. Click here to generate your API Key.

​
API Quota

The API shares its quota with the website, meaning any characters or duration of content generated will count towards your account’s limit, regardless of the interface used.

​
Getting Started with the API

​
Fetching Voice IDs

Before generating text-to-speech, you’ll need a voice_id. To list the voices available to your account, use the following Python code: Example:

import requests
import json

API_KEY = "your_api_key_here"
url = "https://client.camb.ai/apis/list_voices"
headers = {"x-api-key": API_KEY}
response = requests.get(url, headers=headers)
data = response.json()
for voice in data:
    print(f"{voice['voice_name']}; {voice['id']}")

Response

{
  "status_code": 200,
  "message": "OK",
  "payload": [
    {
      "id": 1353,
      "voice_name": "Test 1 Steve Harvey"
    },
    {
      "id": 1355,
      "voice_name": "drawer close2"
    }
  ]
}

​
Fetching Source and Target Languages

To retrieve the list of available source and target languages supported by the API, you can use the following Python examples. These examples demonstrate how to make GET requests to the respective endpoints and parse the response to list the languages.

​
Fetching Source Languages

import requests

API_KEY = "your_api_key_here"
url = "https://api.camb.ai/apis/source_languages"
headers = {
    "Accept": "application/json",
    "x-api-key": API_KEY
}

response = requests.get(url, headers=headers)
data = response.json()
print("Source Languages:")
for language in data:
    print(f"{language['language']} ({language['short_name']})")

Example Response:

{
  "status_code": 200,
  "message": "OK",
  "payload": [
    {
      "id": 1,
      "language": "english (united states)",
      "short_name": "en-us"
    },
    {
      "id": 2,
      "language": "afrikaans (south africa)",
      "short_name": "af-za"
    },
  ]
}

​
Fetching Target Languages

import requests

API_KEY = "your_api_key_here"
url = "https://api.camb.ai/apis/target_languages"
headers = {
    "Accept": "application/json",
    "x-api-key": API_KEY
}

response = requests.get(url, headers=headers)
data = response.json()

print("Target Languages:")
for language in data:
  print(f"{language['language']} ({language['short_name']})")

Example response:

{
  "status_code": 200,
  "message": "OK",
  "payload": [
    {
      "id": 1,
      "language": "english (united states)",
      "short_name": "en-us"
    },
    {
      "id": 2,
      "language": "afrikaans (south africa)",
      "short_name": "af-za"
    },
  ]
}

​
Specify Gender

All of the following are enums that can be passed as gender's value in the API request as necessary. Do not pass a string wherever “gender” is mentioned, you need to pass gender as an integer.

NOT_KNOWN = 0
MALE = 1
FEMALE = 2
NOT_APPLICABLE = 9

​
Text-to-Speech (TTS) Endpoint

The TTS endpoint is your tool for converting text into speech. You’ll need to provide text, a voice_id, and voice settings. For more details, refer to our TTS documentation.

​
Generating Speech

To generate speech using the TTS endpoint, you can use the following Python example. Make sure to replace "your_api_key_here" with your actual API key and "voice_id_here" with the voice_id you obtained from the /list_voices endpoint.

import requests

API_KEY = "your_api_key_here"
url = "https://client.camb.ai/apis/tts"
headers = {
    "Accept": "application/json",
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}
payload = {
    "text": "Hello World!",
    "voice_id": "voice_id_here",  # Replace with actual voice_id
    "language": 1,  # Language ID, e.g., 1 for English
    "gender": 1,    # Gender enum, e.g., 1 for Male
    "age": 0        # Age parameter, e.g., 0 for default
}

response = requests.post(url, headers=headers, json=payload)
response_data = response.json()

# The response will contain a task_id which you can use to track the status of your TTS request
print(response_data)
task_id = response_data["task_id"]

The response will provide you with a task_id that you can use to retrieve the generated speech once it’s ready:

{
  'status_code': 200,
  'message': 'OK',
  'payload': {'task_id': '09b12f04-9f9a-4e92-9723-fab0e21d3e26'}
}

​
Advanced Features

For those looking to delve deeper, Camb.ai’s API offers advanced features such as voice customization and history retrieval. Explore our full API reference for detailed information on these capabilities.

API Reference

Get Started with APIs

How it works

Learn about the technology behind our APIs

​
Full TTS Example:

import requests, os, time

BASE_URL = "https://client.camb.ai/apis"
API_KEY = os.getenv("API_KEY")
HEADERS = {"headers": {"x-api-key": API_KEY}}

tts_payload = {
    "text": "Hello world, my name is Cristiano Ronaldo!",
    "voice_id": 6104,  # Example voice ID
    "language": 1,  # English
    "age": 30,
    "gender": 1,  # Male
}

res = requests.post(f"{BASE_URL}/tts", json=tts_payload, **HEADERS)
task_id = res.json()["task_id"]
print(f"Task ID: {task_id}")

while True:
    res = requests.get(f"{BASE_URL}/tts/{task_id}", **HEADERS)
    status = res.json()["status"]
    print(f"Polling: {status}")
    time.sleep(1.5)
    if status == "SUCCESS":
        run_id = res.json()["run_id"]
        break

print(f"Run ID: {run_id}")
res = requests.get(f"{BASE_URL}/tts_result/{run_id}", **HEADERS, stream=True)
with open("tts_output.wav", "wb") as f:
    for chunk in res.iter_content(chunk_size=1024):
        f.write(chunk)
print("Done!")

​
Dubbing a video Example

import requests, os, time
from dotenv import load_dotenv

load_dotenv()

BASE_URL = "https://client.camb.ai/apis"
API_KEY = os.getenv("API_KEY")
HEADERS = {"headers": {"x-api-key": API_KEY}}

video_url = "https://www.youtube.com/watch?v=W0iQguIT_yE"
payload = {
    'video_url': video_url,
    'source_language': 1, # English
    'target_language': 99, # Malayalam
}
res = requests.post(f"{BASE_URL}/end_to_end_dubbing", json=payload, **HEADERS)
task_id = res.json()["task_id"]
print(f"Task ID: {task_id}")

while True:
    res = requests.get(f"{BASE_URL}/end_to_end_dubbing/{task_id}", **HEADERS)
    status = res.json()["status"]
    print(f"Polling: {status}")
    time.sleep(5)
    if status == "SUCCESS":
        run_id = res.json()["run_id"]
        break

print(f"Run ID: {run_id}")
res = requests.get(f"{BASE_URL}/dubbed_run_info/{run_id}", **HEADERS)
print(res.json())
Create TTS