> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Voice from Description Result
> Retrieve AI-generated voice interpretations and select your preferred vocal style from multiple audio options using `run_id`.
## 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`](create-text-to-voice) endpoint, our system analyzes your parameters and creates not just one, but two 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 two audio previews. Both previews represent 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.
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 two 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:
First, call this endpoint to access your two preview options and determine which one best meets your needs.
Once you've selected your preferred preview, you can use the [`/voices/create-custom-voice`](create-custom-voice) endpoint to establish a permanent voice profile based on that preview.
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 two 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:
```python [expandable] theme={null}
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 or 1, corresponding to the two 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 two 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.
## OpenAPI
````yaml get /text-to-voice-result/{run_id}
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://client.camb.ai/apis
security: []
paths:
/text-to-voice-result/{run_id}:
get:
tags:
- Apis
- Text-to-Voice
summary: Get Text-to-Voice Run Result
operationId: get_text_to_voice_result_text_to_voice_result__run_id__get
parameters:
- name: run_id
in: path
required: true
schema:
$ref: '#/components/schemas/RunIDParam'
description: >-
The unique identifier for the run, which was generated during the
text to voice creation process and returned upon task completion.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TextToVoiceRunInfoResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
RunIDParam:
type: integer
title: Run ID
description: >-
The unique identifier for the run, which was generated during the
creation process and returned upon task completion.
TextToVoiceRunInfoResponse:
properties:
previews:
type: array
items:
type: string
title: Text to Voice Audio URLs
description: >-
An array of two 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.
required: true
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: x-api-key
description: >-
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.
````