voices

Browse the curated voice catalog before calling synthesize. Handy for picking a voice id without reading every TTS provider's API docs.

const { voices, providers } = await speko.voices.list();

Signature

speko.voices.list(params?: VoicesListParams): Promise<VoicesListResult>

Filter to a single provider's voices. Accepts either the routing key (cartesia, xai, alibaba, openai, inworld, elevenlabs) or the catalog suffix form (xai-tts, alibaba-tts, openai-tts).

Returns

`VoicesListResult`

Field	Type	Description
`voices`	`VoiceCatalogEntry[]`	Curated voice roster across the included providers.
`providers`	`VoicesProviderEntry[]`	TTS providers Speko routes to, with their model lists.

`VoiceCatalogEntry`

Field	Type	Description
`vendor`	`string`	Routing-key vendor (matches `allowedProviders.tts` entries).
`id`	`string`	Voice id forwarded verbatim to the provider's TTS API.
`name`	`string`	Human-readable label, e.g. `"Katie (American female)"`.

`VoicesProviderEntry`

Field	Type	Description
`key`	`string`	Catalog key, e.g. `cartesia`, `elevenlabs`, `alibaba-tts`.
`name`	`string`	Human-readable provider name.
`models`	`string[]`	Models available for the `model` field on `synthesize`.
`voicesFetchedLive`	`boolean`	`true` when the provider's voice library is account-scoped (currently only ElevenLabs).

ElevenLabs

ElevenLabs voices are account-scoped, so they are not included in voices — the corresponding providers entry sets voicesFetchedLive: true as a hint to fetch them directly from https://api.elevenlabs.io/v1/voices with the org's key.

Example: pick a voice and synthesize

const { voices } = await speko.voices.list({ provider: 'cartesia' });
const sonia = voices.find((v) => v.name.startsWith('Sonia')) ?? voices[0]!;

await speko.synthesize('Hello world', {
  language: 'en',
  voice: sonia.id,
  constraints: { allowedProviders: { tts: ['cartesia'] } },
});