Create Translated Text-to-Speech

Creates a task to translate input text and generate corresponding speech audio

POST /translated-tts

Create Translated Tts

cURL

curl --request POST \
  --url https://client.camb.ai/apis/translated-tts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "<string>",
  "voice_id": 147320,
  "source_language": "en-us",
  "target_language": "fr-fr",
  "project_name": null,
  "project_description": null,
  "age": 28,
  "formality": 2,
  "gender": 1,
  "chosen_dictionaries": null
}
'

import requests

url = "https://client.camb.ai/apis/translated-tts"

payload = {
    "text": "<string>",
    "voice_id": 147320,
    "source_language": "en-us",
    "target_language": "fr-fr",
    "project_name": None,
    "project_description": None,
    "age": 28,
    "formality": 2,
    "gender": 1,
    "chosen_dictionaries": None
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: '<string>',
    voice_id: 147320,
    source_language: 'en-us',
    target_language: 'fr-fr',
    project_name: null,
    project_description: null,
    age: 28,
    formality: 2,
    gender: 1,
    chosen_dictionaries: null
  })
};

fetch('https://client.camb.ai/apis/translated-tts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client.camb.ai/apis/translated-tts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'voice_id' => 147320,
    'source_language' => 'en-us',
    'target_language' => 'fr-fr',
    'project_name' => null,
    'project_description' => null,
    'age' => 28,
    'formality' => 2,
    'gender' => 1,
    'chosen_dictionaries' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

422

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Transform written content across language barriers with our powerful translated text-to-speech system. This innovative endpoint enables you to seamlessly convert text from one language into spoken audio in another language in a single streamlined process. Whether you’re creating multilingual content, developing educational materials, building accessible applications, or expanding your global reach, this capability allows you to quickly generate localized audio content while maintaining natural pronunciation and intonation specific to the target language.

Once the task is complete, the outputs can be retrieved using these endpoints:

• /translation-result/{run_id}: Returns the translated text.
• /tts-result/{run_id}: Returns the generated voiceover audio

How It Works

When you submit a request to this endpoint, our system processes your input text through a streamlined workflow:

• First, the system creates a dedicated task and returns a unique task_id for tracking.
• Your source text is then accurately translated to the target language using advanced neural machine translation models that preserve meaning andn context.
• Finally, the translated text is converted into natural-sounding speech using language-specific voice models that capture the appropriate pronunciation and intonation of the target language.
• You can monitor the status of your request by polling the /translated-tts/{task_id} endpoint until processing is complete.

Creating Your First Translated Text-to-Speech Request

Let’s examine how to initiate a translated text-to-speech task using Python:

import requests
import json

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
    "Content-Type": "application/json"
}

def create_translated_tts(text, source_language, target_language, voice_id=None):
    """
    Submits a new translated text-to-speech task and returns the task ID for tracking.

    Parameters:
    - text: The source text to be translated and converted to speech
    - source_language: Locale tag of the input text (e.g., "en-us"); numeric IDs (e.g. 1) still work but are deprecated
    - target_language: Locale tag for the desired output (e.g., "es-es")
    - voice_id: Optional specific voice to use for the target language
    """
    try:
        # Prepare the request body
        payload = {
            "text": text,
            "source_language": source_language,
            "target_language": target_language
        }

        # Add voice_id if specified
        if voice_id:
            payload["voice_id"] = voice_id

        # Submit the request
        response = requests.post(
            "https://client.camb.ai/apis/translated-tts",
            headers=headers,
            data=json.dumps(payload)
        )

        # Verify the request was successful
        response.raise_for_status()

        # Extract the task ID from the response
        result = response.json()
        task_id = result.get("task_id")
        run_id = result.get("run_id")

        print(f"Translated TTS task submitted successfully! Task ID: {task_id}")
        print(f"Run ID for retrieving results: {run_id}")
        return task_id, run_id

    except requests.exceptions.RequestException as e:
        print(f"Error submitting translated TTS task: {e}")
        if hasattr(e, 'response') and e.response is not None:
            print(f"Response content: {e.response.text}")
        return None, None

# Example usage
source_text = "Welcome to our global product demonstration. We're excited to share these new features with you."
task_id, run_id = create_translated_tts(
    text=source_text,
    source_language="en-us",  # Locale tag. Numeric IDs (e.g. 1) still work but are deprecated.
    target_language="ja-jp"
)

Monitoring Your Translation and Speech Generation Progress

After submission, your task enters our processing pipeline. You can monitor the progress by polling the status endpoint:

def check_translated_tts_status(task_id):
    """
    Checks the status of a translated text-to-speech task.
    Returns the current status and any available result information.

    Parameters:
    - task_id: The ID of the task to check
    """
    if not task_id:
        print("No task ID provided.")
        return None

    try:
        response = requests.get(
            f"https://client.camb.ai/apis/translated-tts/{task_id}",
            headers=headers
        )

        # Verify the request was successful
        response.raise_for_status()

        # Parse the status information
        status_data = response.json()
        print(f"Current status: {status_data['status']}")

        # If the task is complete, show how to access results
        if status_data['status'] == "SUCCESS":
            print("Translation and speech generation completed successfully!")
            print(f"Use the run_id to retrieve your results.")
            print(f"- Translation: GET /translation-result/{status_data.get('run_id')}")
            print(f"- Audio: GET /tts-result/{status_data.get('run_id')}")

        return status_data

    except requests.exceptions.RequestException as e:
        print(f"Error checking task status: {e}")
        return None

# Check the status of your task
status_info = check_translated_tts_status(task_id)

Retrieving Your Results

Once your task is complete, you can retrieve both the translated text and the generated audio using the provided run_id:

def get_translation_result(run_id):
    """
    Retrieves the translated text result.

    Parameters:
    - run_id: The run ID returned from the initial request
    """
    try:
        response = requests.get(
            f"https://client.camb.ai/apis/translation-result/{run_id}",
            headers=headers
        )

        response.raise_for_status()
        result = response.json()

        print(f"Translation successful!")
        print(f"Translated text: {result.get('translated_text')}")
        return result

    except requests.exceptions.RequestException as e:
        print(f"Error retrieving translation: {e}")
        return None

def get_tts_result(run_id):
    """
    Retrieves the generated audio file.

    Parameters:
    - run_id: The run ID returned from the initial request
    """
    try:
        response = requests.get(
            f"https://client.camb.ai/apis/tts-result/{run_id}",
            headers=headers
        )

        response.raise_for_status()
        result = response.json()

        print(f"Audio retrieval successful!")
        print(f"Audio URL: {result.get('audio_url')}")
        return result

    except requests.exceptions.RequestException as e:
        print(f"Error retrieving audio: {e}")
        return None

# Retrieve your results
translation = get_translation_result(run_id)
audio = get_tts_result(run_id)

Best Practices for Translated Text-to-Speech

To achieve the highest quality results for your multilingual audio content:

1. Provide Clear Source Text: Ensure your source text is free of grammatical errors, unusual abbreviations, or ambiguous phrases to improve translation accuracy.

2. Consider Cultural Context: Be mindful of cultural references that may not translate effectively across languages, and adapt your content accordingly.

3. Use Appropriate Sentence Length: For optimal speech generation, break long, complex sentences into shorter ones, especially for languages that differ structurally from the source.

Supported Languages & Voices

Our system supports a wide range of language pairs for translation and speech synthesis. The quality and naturalness of speech may vary depending on the specific language combinations. Checkout the /target-languages endpoint for a list of supported languages and /list-voices endpoint for a list of available voices which includes public voices and your own custom voices.

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

Parameters for initiating a translation and text-to-speech task, including source text, language preferences, and voice characteristics.

text · string · required

The input text content that you want to translate and convert to speech. Provide clear, well-structured text for optimal results.

voice_id · integer · default: 147320 · required

A unique identifier for the specific voice to use for speech synthesis in the target language. Each voice has distinct characteristics including tone, accent, and speaking style.

source_language · string · required

The language of the input text. Pass a locale tag (en-us, fr-fr, es-es). Numeric language IDs (1 or "1") still work but are deprecated. See all source languages.

Example:

"en-us"

target_language · string · required

The target output language. Pass a locale tag (fr-fr, es-es, de-de). Numeric language IDs still work but are deprecated. See all target languages.

Example:

"fr-fr"

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

Example:

null

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

Example:

null

age · integer | null · default: 28

The simulated age of the speaker in years, which influences voice characteristics. Defaults to 28 if not specified. Set to null to use the default voice age.

formality · enum<integer> | null · default: 2

The level of formality to use for the translation. Values range from casual (1), with a default of 2 (formal). This affects the translation's tone and word choice based on cultural norms of the target language.

Available options: 1, 2

gender · enum<integer> | null · default: 1

The gender of the synthesized voice. Influences voice characteristics based on typical speech patterns. Defaults to 1 (typically representing male).

Available options: 0, 1, 2, 9

chosen_dictionaries · integer[] | null

An optional list of dictionary IDs selected by the user. Each entry must be an integer corresponding to a valid dictionary ID. If provided, at least one ID is required.

Minimum array length: 1

Response

200

application/json

Successful Response