Implementation:Elevenlabs Elevenlabs python TextToVoiceRawClient

Field	Value
Sources	src/elevenlabs/text_to_voice/raw_client.py, src/elevenlabs/text_to_voice/client.py
Domains	Voice Design, Text-to-Voice, Voice Generation
Last Updated	2026-02-15

Overview

The RawTextToVoiceClient provides the low-level HTTP implementation for the Text-to-Voice API in the ElevenLabs SDK. This API allows users to design, preview, create, and remix voices using natural language text descriptions. The workflow involves two phases: first, generating voice previews from a description, then creating a permanent voice from a selected preview.

The raw client returns HttpResponse wrapper objects that include both the parsed data and the full HTTP response metadata (status code, headers, etc.). The high-level TextToVoiceClient provides the same methods but returns only the parsed model objects. It also provides access to a preview sub-client for streaming voice previews.

The client is accessible via client.text_to_voice (high-level) or client.text_to_voice.with_raw_response (raw). Both synchronous and asynchronous variants are provided.

API Endpoints

Method	HTTP	Endpoint
create_previews()	POST	v1/text-to-voice/create-previews
create()	POST	v1/text-to-voice
design()	POST	v1/text-to-voice/design
remix()	POST	v1/text-to-voice/{voice_id}/remix

Code Reference

Source Location

• Raw client: src/elevenlabs/text_to_voice/raw_client.py
• High-level client: src/elevenlabs/text_to_voice/client.py

Class Signatures

class RawTextToVoiceClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper): ...

class AsyncRawTextToVoiceClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper): ...

Import

The raw client is accessed through the high-level client's with_raw_response property:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
raw_client = client.text_to_voice.with_raw_response  # RawTextToVoiceClient instance

I/O Contract

create_previews()

Create voice previews from a text prompt. This is a simplified interface for voice generation.

Input Parameters:

Parameter	Type	Required	Description
voice_description	str	Yes	Description to use for the created voice
output_format	typing.Optional[AllowedOutputFormats]	No	The output format of the generated audio
text	typing.Optional[str]	No	Text to generate; length must be between 100 and 1000
auto_generate_text	typing.Optional[bool]	No	Whether to automatically generate text suitable for the voice description
loudness	typing.Optional[float]	No	Volume level of the generated voice. -1 is quietest, 1 is loudest, 0 corresponds to roughly -24 LUFS
quality	typing.Optional[float]	No	Higher quality results in better voice output but less variety
seed	typing.Optional[int]	No	Random number that controls the voice generation. Same seed with same inputs produces same voice
guidance_scale	typing.Optional[float]	No	Controls how closely the AI follows the prompt. Lower values give more creative freedom, higher values are more literal
should_enhance	typing.Optional[bool]	No	Whether to enhance the voice description using AI. Defaults to False
request_options	typing.Optional[RequestOptions]	No	Request-specific configuration

Output:

Type (Raw)	Type (High-level)	Description
HttpResponse[VoiceDesignPreviewResponse]	VoiceDesignPreviewResponse	Voice preview results with generated_voice_id and audio samples

create()

Create a permanent voice from a previously generated voice preview. Call this after obtaining a generated_voice_id from create_previews() or design().

Input Parameters:

Parameter	Type	Required	Description
voice_name	str	Yes	Name to use for the created voice
voice_description	str	Yes	Description to use for the created voice
generated_voice_id	str	Yes	The generated_voice_id from a preview response
labels	typing.Optional[typing.Dict[str, typing.Optional[str]]]	No	Optional metadata to add to the created voice
played_not_selected_voice_ids	typing.Optional[typing.Sequence[str]]	No	List of voice ids that were played but not selected. Used for RLHF
request_options	typing.Optional[RequestOptions]	No	Request-specific configuration

Output:

Type (Raw)	Type (High-level)	Description
HttpResponse[Voice]	Voice	The created voice object

design()

Design a voice via a prompt with advanced options. Returns a list of voice previews, each with a generated_voice_id and a base64-encoded MP3 audio sample.

Input Parameters:

Parameter	Type	Required	Description
voice_description	str	Yes	Description to use for the created voice
output_format	typing.Optional[AllowedOutputFormats]	No	Output format (e.g., mp3_22050_32). Higher bitrates may require higher subscription tiers
model_id	typing.Optional[VoiceDesignRequestModelModelId]	No	Model to use. Possible values: eleven_multilingual_ttv_v2, eleven_ttv_v3
text	typing.Optional[str]	No	Text to generate; length must be between 100 and 1000
auto_generate_text	typing.Optional[bool]	No	Whether to automatically generate text suitable for the voice description
loudness	typing.Optional[float]	No	Volume level. -1 is quietest, 1 is loudest
seed	typing.Optional[int]	No	Random seed for reproducible voice generation
guidance_scale	typing.Optional[float]	No	Controls prompt adherence. Lower values are more creative, higher values more literal
stream_previews	typing.Optional[bool]	No	If true, only generated IDs are returned (previews can be streamed separately)
should_enhance	typing.Optional[bool]	No	Whether to enhance the description using AI. Defaults to False
remixing_session_id	typing.Optional[str]	No	The remixing session id
remixing_session_iteration_id	typing.Optional[str]	No	The remixing session iteration id
quality	typing.Optional[float]	No	Higher quality results in better output but less variety
reference_audio_base_64	typing.Optional[str]	No	Base64-encoded reference audio. Only supported with eleven_ttv_v3 model
prompt_strength	typing.Optional[float]	No	Balance of prompt vs. reference audio (0 = no prompt, 1 = no reference). Only with eleven_ttv_v3
request_options	typing.Optional[RequestOptions]	No	Request-specific configuration

Output:

Type (Raw)	Type (High-level)	Description
HttpResponse[VoiceDesignPreviewResponse]	VoiceDesignPreviewResponse	Voice previews with generated_voice_id and base64 audio samples

remix()

Remix an existing voice via a prompt. Returns a list of modified voice previews.

Input Parameters:

Parameter	Type	Required	Description
voice_id	str	Yes	Voice ID of the voice to remix
voice_description	str	Yes	Description of the changes to make to the voice
output_format	typing.Optional[AllowedOutputFormats]	No	Output format of the generated audio
text	typing.Optional[str]	No	Text to generate; length must be between 100 and 1000
auto_generate_text	typing.Optional[bool]	No	Whether to automatically generate text suitable for the voice description
loudness	typing.Optional[float]	No	Volume level. -1 is quietest, 1 is loudest
seed	typing.Optional[int]	No	Random seed for reproducible generation
guidance_scale	typing.Optional[float]	No	Controls prompt adherence
stream_previews	typing.Optional[bool]	No	If true, only generated IDs are returned
remixing_session_id	typing.Optional[str]	No	The remixing session id
remixing_session_iteration_id	typing.Optional[str]	No	The remixing session iteration id
prompt_strength	typing.Optional[float]	No	Balance of prompt vs. reference audio. Only with eleven_ttv_v3
request_options	typing.Optional[RequestOptions]	No	Request-specific configuration

Output:

Type (Raw)	Type (High-level)	Description
HttpResponse[VoiceDesignPreviewResponse]	VoiceDesignPreviewResponse	Remixed voice previews with generated_voice_id and audio samples

Error Handling

All methods may raise:

• UnprocessableEntityError (HTTP 422) -- contains an HttpValidationError body with validation details.
• ApiError -- for all other non-2xx HTTP status codes.

Usage Examples

Create Voice Previews

from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="YOUR_API_KEY",
)
previews = client.text_to_voice.create_previews(
    output_format="mp3_22050_32",
    voice_description="A sassy squeaky mouse",
)

Design a Voice with Advanced Options

from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="YOUR_API_KEY",
)
previews = client.text_to_voice.design(
    output_format="mp3_22050_32",
    voice_description="A sassy squeaky mouse",
)

Create a Permanent Voice from Preview

from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="YOUR_API_KEY",
)
voice = client.text_to_voice.create(
    voice_name="Sassy squeaky mouse",
    voice_description="A sassy squeaky mouse",
    generated_voice_id="37HceQefKmEi3bGovXjL",
)

Remix an Existing Voice

from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="YOUR_API_KEY",
)
remixed = client.text_to_voice.remix(
    voice_id="21m00Tcm4TlvDq8ikWAM",
    output_format="mp3_22050_32",
    voice_description="Make the voice have a higher pitch.",
)

Full Workflow: Design, Preview, and Create

from elevenlabs import ElevenLabs

client = ElevenLabs(
    api_key="YOUR_API_KEY",
)

# Step 1: Design voice previews
previews = client.text_to_voice.design(
    voice_description="A warm, friendly narrator with a British accent",
    output_format="mp3_22050_32",
    auto_generate_text=True,
)

# Step 2: Select a preview and create the voice
# (use generated_voice_id from one of the previews)
voice = client.text_to_voice.create(
    voice_name="British Narrator",
    voice_description="A warm, friendly narrator with a British accent",
    generated_voice_id="selected_generated_voice_id",
)

Raw Response Access

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

raw_response = client.text_to_voice.with_raw_response.create_previews(
    voice_description="A sassy squeaky mouse",
    output_format="mp3_22050_32",
)
print(raw_response.response.status_code)
print(raw_response.response.headers)
print(raw_response.data)

Async Usage

import asyncio
from elevenlabs import AsyncElevenLabs

client = AsyncElevenLabs(
    api_key="YOUR_API_KEY",
)

async def main() -> None:
    # Create voice previews
    previews = await client.text_to_voice.create_previews(
        output_format="mp3_22050_32",
        voice_description="A sassy squeaky mouse",
    )

    # Create a permanent voice
    voice = await client.text_to_voice.create(
        voice_name="Sassy squeaky mouse",
        voice_description="A sassy squeaky mouse",
        generated_voice_id="37HceQefKmEi3bGovXjL",
    )

    # Remix an existing voice
    remixed = await client.text_to_voice.remix(
        voice_id="21m00Tcm4TlvDq8ikWAM",
        output_format="mp3_22050_32",
        voice_description="Make the voice have a higher pitch.",
    )

asyncio.run(main())

Related Pages

• Elevenlabs_Elevenlabs_python_SamplesClient -- Voice sample management
• Elevenlabs_Elevenlabs_python_ForcedAlignmentClient -- Forced alignment of audio with text transcripts
• Elevenlabs_Elevenlabs_python_ConversationalAIRawClient -- Conversational AI knowledge base and RAG index management
• Elevenlabs_Elevenlabs_python_Environment -- Environment and base URL configuration