GET
/
text-to-voice-result
/
{run_id}
Get Text-to-Voice Run Result
curl --request GET \
  --url https://client.camb.ai/apis/text-to-voice-result/{run_id} \
  --header 'x-api-key: <api-key>'
{
  "previews": [
    "<string>"
  ]
}

​
Understanding Voice Generation Results

This endpoint provides access to the results of your voice generation request after processing has completed. When you submit a text description through the /text-to-voice endpoint, our system analyzes your parameters and creates not just one, but three distinct voice interpretations based on your description. This approach gives you the opportunity to compare different vocal realizations and select the one that best matches your intended use case.

​
How to Access Your Voice Interpretations

To retrieve your voice generation results, you’ll need the run_id that was provided when you initially submitted your voice generation request. This identifier uniquely references your specific generation task and allows you to access its results once processing is complete. The endpoint follows this structure: 
GET /text-to-voice-result/{run_id}
Where {run_id} should be replaced with your actual run identifier. For example: 
GET /text-to-voice-result/8827

​
Understanding the Response

When you call this endpoint, the system returns a JSON object containing URLs to three audio previews. Each preview represents a different interpretation of your voice description, speaking the same text content you provided during submission. These previews have the following characteristics:

​
Preview Variations Explained

  1. Preview 1: Primary Interpretation This first interpretation closely adheres to the core parameters of your description. It represents the system’s primary understanding of your requested voice characteristics, focusing on the fundamental attributes you specified such as gender, age range, and basic tonal qualities.
  2. Preview 2: Nuanced Alternative The second interpretation explores alternative expressions of your description with modified pacing and emphasis patterns. This version might adjust factors like speaking rate, rhythmic patterns, and the relative emphasis placed on different syllables or words, creating a subtly different feel while still honoring your core description.
  3. Preview 3: Boundary Exploration The third interpretation takes a more experimental approach, testing the boundaries of your description parameters. This version might intensify certain characteristics or introduce complementary vocal qualities that weren’t explicitly stated but might enhance the overall effect of the voice.
Each of these interpretations applies different:
  • Emotional cadence variations: How emotional qualities rise and fall throughout the speech
  • Prosody adjustments: Alterations in intonation patterns, rhythm, stress, and tonal qualities
  • Phonetic emphasis patterns: Changes in how individual sounds are articulated and emphasized
These variations are carefully calibrated to give you meaningful choices rather than random alternatives. By comparing the three interpretations side by side, you can identify which vocal qualities best serve your specific needs.

​
From Preview to Permanent Voice

The preview voices you receive are temporary by design, intended to help you evaluate different interpretations of your description. However, you can convert any preview you particularly like into a permanent custom voice that becomes available throughout our speech synthesis ecosystem.

​
Creating a Permanent Voice Profile

The process of converting a preview into a permanent voice involves these key steps:
1

Retrieve and evaluate your preview samples

First, call this endpoint to access your three preview options and determine which one best meets your needs.
2

Create a permanent voice profile

Once you’ve selected your preferred preview, you can use the /voices/create-custom-voice endpoint to establish a permanent voice profile based on that preview.
3

Integrate your custom voice

After creation, your new voice becomes available for use across all compatible speech synthesis services within our platform.
This workflow allows you to move from concept (your text description) to evaluation (the three previews) to implementation (your permanent custom voice) in a streamlined process.

​
Implementation Example

The following Python code demonstrates how to retrieve your preview samples and convert your preferred option into a permanent custom voice: 
import requests

BASE_URL = "https://client.camb.ai/apis"

def create_voice_from_preview(run_id, preview_index=0):
    """
    Converts temporary preview into permanent custom voice

    This function performs a complete workflow:
    1. Retrieves the specified preview audio using the run_id
    2. Downloads the selected preview to a local file
    3. Creates a permanent voice clone from this sample

    Parameters:
        run_id (int): The unique identifier of your voice generation task
        preview_index (int): Which preview to use (0, 1, or 2, corresponding to the three previews)

    Returns:
        dict: Response from the custom voice creation API
    """
    # Retrieve preview URL from the results endpoint
    preview_res = requests.get(f"{BASE_URL}/text-to-voice-result/{run_id}")
    preview_url = preview_res.json()['previews'][preview_index]

    # Download the selected audio sample to a local file
    audio_file = requests.get(preview_url).content
    with open("voice_sample.mp3", "wb") as f:
        f.write(audio_file)

    # Create a permanent custom voice using the downloaded sample
    files = {'file': open('voice_sample.mp3', 'rb')}
    data = {
        'voice_name': 'My Campaign Voice',  # Choose a descriptive name for your voice
        'gender': 1,  # Male (matches preview characteristics)
        'age': 35     # Estimated vocal age
    }

    creation_res = requests.post(
        f"{BASE_URL}/create-custom-voice",
        files=files,
        data=data,
        headers={"x-api-key": API_KEY}
    )

    return creation_res.json()

# Example usage
voice_profile = create_voice_from_preview(run_id=8827, preview_index=1)
print(f"New voice ID: {voice_profile['voice_id']}")

​
Best Practices for Voice Selection

When evaluating your preview options, consider these factors to make the most effective choice:
  1. Content context: Different voices may be more suitable depending on whether your content is informational, narrative, promotional, or instructional.
  2. Audience expectations: Consider what vocal qualities would resonate best with your target audience based on their demographic and psychographic characteristics.
  3. Brand alignment: If the voice will represent your brand, assess which interpretation best embodies your brand personality and values.
  4. Emotional impact: Listen for how each voice conveys emotional subtext and choose the one that elicits the desired emotional response.
  5. Technical qualities: Consider practical aspects like clarity, intelligibility across different listening environments, and how well the voice handles specialized vocabulary.
By comparing your three preview options with these considerations in mind, you can select the voice interpretation that will most effectively serve your communication objectives.
To ensure the best experience, always verify that your voice generation task has completed successfully before attempting to access the results
By understanding the nuances of voice interpretation and making thoughtful selections from your preview options, you can establish voice profiles that authentically convey your message and connect with your audience.

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 text to voice creation process and returned upon task completion.

Response

Successful Response

​
previews
string[]

An array of three distinct URL strings, each pointing to a unique voice sample generated from your text prompt. These samples represent different voice interpretations based on your description, allowing you to compare options before selecting your preferred voice for further use.