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",
"language": 1,
"gender": 1,
"age": 0
}
response = requests.post(url, headers=headers, json=payload)
response_data = response.json()
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.
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,
"language": 1,
"age": 30,
"gender": 1,
}
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,
'target_language': 99,
}
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())