Manage voice library including listing, searching, creating, updating, and deleting voices. Supports instant voice cloning (IVC), professional voice cloning (PVC), and voice sharing.
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Access this API via: client.voicesGet list of all available voices for the user.
/**
* @param request - Optional filter parameters
* @param requestOptions - Optional request configuration
* @returns List of voices
* @throws UnprocessableEntityError if request fails
*/
client.voices.getAll(
request?: VoicesGetAllRequest,
requestOptions?: RequestOptions
): HttpResponsePromise<GetVoicesResponse>;
interface VoicesGetAllRequest {
/** Include legacy voices in response */
show_legacy?: boolean;
}
interface GetVoicesResponse {
voices: Voice[];
}
interface Voice {
voice_id: string;
name: string;
samples?: VoiceSample[];
category?: string;
fine_tuning?: FineTuningResponse;
labels?: Record<string, string>;
description?: string;
preview_url?: string;
available_for_tiers?: string[];
settings?: VoiceSettings;
sharing?: VoiceSharingResponse;
high_quality_base_model_ids?: string[];
safety_control?: string;
voice_verification?: VoiceVerificationResponse;
}
interface VoiceSample {
sample_id?: string;
file_name?: string;
mime_type?: string;
size_bytes?: number;
hash?: string;
duration_secs?: number;
remove_background_noise?: boolean;
has_isolated_audio?: boolean;
has_isolated_audio_preview?: boolean;
trim_start?: number;
trim_end?: number;
}
interface FineTuningResponse {
is_allowed_to_fine_tune?: boolean;
state?: Record<string, string>;
verification_failures?: string[];
verification_attempts_count?: number;
manual_verification_requested?: boolean;
language?: string;
progress?: Record<string, number>;
message?: Record<string, string>;
dataset_duration_seconds?: number;
slice_ids?: string[];
max_verification_attempts?: number;
next_max_verification_attempts_reset_unix_ms?: number;
}
interface VoiceSharingResponse {
status?: string;
history_item_sample_id?: string;
date_unix?: number;
whitelisted_emails?: string[];
public_owner_id?: string;
original_voice_id?: string;
financial_rewards_enabled?: boolean;
free_users_allowed?: boolean;
live_moderation_enabled?: boolean;
rate?: number;
fiat_rate?: number;
notice_period?: number;
disable_at_unix?: number;
voice_mixing_allowed?: boolean;
featured?: boolean;
category?: string;
reader_app_enabled?: boolean;
image_url?: string;
ban_reason?: string;
liked_by_count?: number;
cloned_by_count?: number;
name?: string;
description?: string;
labels?: Record<string, string>;
review_status?: string;
review_message?: string;
enabled_in_library?: boolean;
instagram_username?: string;
twitter_username?: string;
youtube_username?: string;
tiktok_username?: string;
}
interface VoiceVerificationResponse {
requires_verification: boolean;
is_verified: boolean;
verification_failures: string[];
verification_attempts_count: number;
language?: string;
}Search voices with advanced filtering, sorting, and pagination.
/**
* @param request - Search and filter parameters
* @param requestOptions - Optional request configuration
* @returns Paginated voice search results
* @throws UnprocessableEntityError if request fails
*/
client.voices.search(
request?: VoicesSearchRequest,
requestOptions?: RequestOptions
): HttpResponsePromise<GetVoicesV2Response>;
interface VoicesSearchRequest {
/** Pagination token for next page */
next_page_token?: string;
/** Number of results per page */
page_size?: number;
/** Search query string */
search?: string;
/** Sort field (e.g., "created_date", "name") */
sort?: string;
/** Sort direction ("asc" or "desc") */
sort_direction?: "asc" | "desc";
/** Voice type filter (e.g., "professional", "instant") */
voice_type?: string;
/** Category filter */
category?: string;
/** Fine tuning state filter */
fine_tuning_state?: string;
/** Collection ID filter */
collection_id?: string;
/** Include total count in response */
include_total_count?: boolean;
/** Filter by specific voice IDs */
voice_ids?: string[];
}
interface GetVoicesV2Response {
voices: Voice[];
next_page_token?: string;
has_more: boolean;
total_count?: number;
}Get metadata about a specific voice.
/**
* @param voice_id - ID of the voice
* @param request - Optional parameters
* @param requestOptions - Optional request configuration
* @returns Voice metadata
* @throws UnprocessableEntityError if request fails
*/
client.voices.get(
voice_id: string,
request?: VoicesGetRequest,
requestOptions?: RequestOptions
): HttpResponsePromise<Voice>;
interface VoicesGetRequest {
/** Include voice settings in response */
with_settings?: boolean;
}Delete a voice by its ID.
/**
* @param voice_id - ID of the voice
* @param requestOptions - Optional request configuration
* @returns Deletion confirmation
* @throws UnprocessableEntityError if request fails
*/
client.voices.delete(
voice_id: string,
requestOptions?: RequestOptions
): HttpResponsePromise<DeleteVoiceResponseModel>;
interface DeleteVoiceResponseModel {
success: boolean;
}Edit a voice created by you.
/**
* @param voice_id - ID of the voice
* @param request - Updated voice metadata and samples
* @param requestOptions - Optional request configuration
* @returns Update confirmation
* @throws UnprocessableEntityError if request fails
*/
client.voices.update(
voice_id: string,
request: BodyEditVoiceV1VoicesVoiceIdEditPost,
requestOptions?: RequestOptions
): HttpResponsePromise<EditVoiceResponseModel>;
interface BodyEditVoiceV1VoicesVoiceIdEditPost {
/** New voice name */
name?: string;
/** Voice description */
description?: string;
/** Audio files to add as samples (File objects or URLs) */
files?: File[];
/** Labels/tags for the voice as serialized JSON string */
labels?: string;
/** If set, will remove background noise for voice samples using audio isolation model. If samples don't include background noise, it can make quality worse */
removeBackgroundNoise?: boolean;
}
interface EditVoiceResponseModel {
success: boolean;
}Add a shared voice to your collection.
/**
* @param public_user_id - Public user ID of voice owner
* @param voice_id - ID of the shared voice
* @param request - Voice metadata
* @param requestOptions - Optional request configuration
* @returns New voice ID
* @throws UnprocessableEntityError if request fails
*/
client.voices.share(
public_user_id: string,
voice_id: string,
request: BodyAddSharedVoiceV1VoicesAddPublicUserIdVoiceIdPost,
requestOptions?: RequestOptions
): HttpResponsePromise<AddVoiceResponseModel>;
interface BodyAddSharedVoiceV1VoicesAddPublicUserIdVoiceIdPost {
/** New name for the voice */
new_name: string;
}
interface AddVoiceResponseModel {
voice_id: string;
}Find shared voices similar to provided audio sample.
/**
* @param request - Audio sample and search parameters
* @param requestOptions - Optional request configuration
* @returns Similar voices
* @throws UnprocessableEntityError if request fails
*/
client.voices.findSimilarVoices(
request: BodyGetSimilarLibraryVoicesV1SimilarVoicesPost,
requestOptions?: RequestOptions
): HttpResponsePromise<GetLibraryVoicesResponse>;
interface BodyGetSimilarLibraryVoicesV1SimilarVoicesPost {
/** Audio file to match against */
audio_file: File | Blob;
/** Similarity threshold (0.0 to 1.0) */
similarity_threshold?: number;
/** Maximum number of results */
top_k?: number;
}import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Get all voices
const allVoices = await client.voices.getAll();
console.log("Available voices:", allVoices.voices.length);
// Search for specific voices
const searchResults = await client.voices.search({
search: "female narrator",
voice_type: "professional",
page_size: 10,
});
for (const voice of searchResults.voices) {
console.log(`${voice.name}: ${voice.description}`);
}// Get current voice
const voice = await client.voices.get("voice-id", { with_settings: true });
// Modify the voice metadata
await client.voices.update("voice-id", {
name: "Updated Voice Name",
description: "New description",
labels: {
...voice.labels,
category: "narration",
},
});// Find voices similar to an audio sample
const audioSample = await readFile("reference.mp3");
const similarVoices = await client.voices.findSimilarVoices({
audio_file: new File([audioSample], "reference.mp3"),
similarity_threshold: 0.7,
top_k: 5,
});
console.log(`Found ${similarVoices.voices.length} similar voices`);