Get Voice from Description Result

​

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:

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.

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.