GET
/
tts-result
/
{run_id}
curl --request GET \
  --url https://client.camb.ai/apis/tts-result/{run_id} \
  --header 'x-api-key: <api-key>'
"<string>"

This endpoint is the final step in your text-to-speech journey, where you retrieve your completed audio file. Once your task has reached a SUCCESS status and you’ve received a run_id, you can use this endpoint to access your generated audio and incorporate it into your application.

​
How to Use this Endpoint

Retrieving your generated audio is straightforward - simply make a GET request to this endpoint with the run_id you received when your task completed. The system will respond by providing your audio in your preferred format.

​
Understanding Response Options

This endpoint offers flexibility in how you receive your audio content. You can specify your preference using the output_type parameter:

Output TypeDescriptionBest For
raw_bytesDirect streaming of audio data (default option)Immediate playback or saving to local storage
file_urlJSON response with a URL to download the audio fileWhen you need to share or store the audio URL

​
Working with Raw Bytes

When using the default raw_bytes output type, the endpoint streams the audio data directly to your application. This approach is ideal when you want to:

  1. Save the audio file to your local system
  2. Process the audio data immediately in your application
  3. Play the audio without storing it permanently
The streaming approach is particularly efficient for handling larger audio files as it processes the data in manageable chunks rather than loading everything into memory at once.

​
Working with File URLs

If you prefer to receive a URL pointing to your audio file instead of the raw data, specify output_type=file_url. The response will be a JSON object containing a URL where the audio file can be accessed. This approach is beneficial when:

  1. You need to share the audio file with others
  2. Embed the audio in web content
  3. Handle the download process separately from retrieval
Note that file URLs have an expiration time, so download or use them promptly rather than storing them long-term.

​
Examples

​
Saving Audio to a File

Here’s how to retrieve and save your generated audio using Python:

import requests

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# The run_id you received when your task completed successfully
run_id = "abc123xyz"  # Replace with your actual run_id

def download_audio_file(run_id, output_filename="generated_speech.flac"):
    """
    Downloads the generated audio file and saves it to the specified location.

    Args:
        run_id: The unique identifier for the completed TTS task
        output_filename: Where to save the audio file (defaults to 'generated_speech.flac')

    Returns:
        bool: True if successful, False otherwise
    """
    print(f"Downloading audio for run_id: {run_id}")

    try:
        # Make the request with streaming enabled
        # The 'stream=True' parameter is crucial for handling the audio data efficiently
        response = requests.get(
            f"https://client.camb.ai/apis/tts-result/{run_id}",
            headers=headers,
            stream=True  # This enables processing the response in chunks
        )

        # Check if the request was successful
        response.raise_for_status()

        # Save the streaming audio to a file
        with open(output_filename, "wb") as audio_file:
            # Process the response in chunks to handle large audio files efficiently
            # The chunk_size determines how much data to process at once
            for chunk in response.iter_content(chunk_size=1024):
                if chunk:  # Filter out keep-alive chunks
                    audio_file.write(chunk)

        print(f"Audio successfully saved to {output_filename}!")
        return True

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

# Call the function to download your audio
success = download_audio_file(run_id)

if success:
    print("You can now use this audio file in your application!")

​
Getting a File URL

If you prefer to receive a URL to the audio file instead:

import requests

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
}

# The run_id you received when your task completed successfully
run_id = "abc123xyz"  # Replace with your actual run_id

# Request a URL instead of raw bytes
params = {
    "output_type": "file_url"
}

# Make the request
response = requests.get(
    f"https://client.camb.ai/apis/tts-result/{run_id}",
    headers=headers,
    params=params
)

# Check if the request was successful
response.raise_for_status()

# Get the URL from the response
url_data = response.json()
audio_url = url_data.get("output_url")

print(f"Your audio is available at: {audio_url}")
print("You can now share this URL or use it to embed the audio in your application.")

​
Next Steps

Now that you’ve successfully retrieved your generated audio, you can:

  1. Incorporate it into your applications or websites.
  2. Process it further with audio editing tools.
  3. Combine multiple audio segments into a cohesive narrative.
  4. Share it with your users through your platform.

With these capabilities, you have everything you need to build rich, accessible voice experiences into your applications.

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.

Path Parameters

​
run_id
integer
required

The unique identifier for the run, which was generated during the creation process and returned upon task completion.

Query Parameters

​
output_type
enum<string>
default:raw_bytes

The type of the Text-to-Speech output to return. Either streamable audio bytes or a URL to the generated file.

Available options:
raw_bytes,
file_url

Response

200
audio/flac

Successful Response

The generated audio file bytes in FLAC format, representing the speech created from the Text-to-Speech task.