Skip to Content

Text to speech

The @preternatural-js/client-sdk/text-to-speech subpath provides TextToSpeechClient for ElevenLabs and Rime AI. Configure the provider account, product and matching speech usage rule first. This client uses the customer’s gateway authentication; do not send the provider key from your application.

import { ExternalServiceProvider } from '@preternatural-js/client-sdk' import { TextToSpeechClient } from '@preternatural-js/client-sdk/text-to-speech' const speech = new TextToSpeechClient(client, { provider: ExternalServiceProvider.elevenlabs, productId: 'your-product-id' }) const models = await speech.listModels() const modelId = models[0]?.id const languages = await speech.listLanguages(modelId) const voices = await speech.listVoices({ modelId, lang: 'en' })

Catalogs are public gateway reads. An empty catalog is not permission to invent a voice or model ID. For Rime AI, use ExternalServiceProvider.rimeAI.

Generate audio

const voice = voices[0] if (!voice) throw new Error('No voice is available') const audio = await speech.textToSpeech({ text: 'Welcome to the application.', voice: voice.id, modelId, language: 'en' })

The result is an ArrayBuffer. Decode or save it according to the provider’s output format; this helper does not transcode audio or expose an output-format option. productId on a request overrides the client default. Choose model and voice explicitly when reproducible behavior matters; the source defaults are eleven_v3 and coda respectively.

Stream audio

const bytes = await speech.streamTextToSpeech({ text: 'A longer passage to read aloud.', voice: voice.id, modelId }) const reader = bytes.getReader() try { while (true) { const chunk = await reader.read() if (chunk.done) break await consumeAudioBytes(chunk.value) } } finally { await reader.cancel() reader.releaseLock() }

The stream contains audio bytes, not chat SSE events. Cancelling consumption does not undo audio already generated or measured. The speech helper has no per-request signal parameter; transport timeouts and cancellation of the response reader are separate controls.

Provider options and failures

ElevenLabs accepts voiceSettings with stability, similarityBoost, style and useSpeakerBoost. Other providers ignore it. Do not treat it as a portable Rime setting.

Catalog failures, malformed responses and rejected generation throw ApiClientError. ElevenLabs quota_exceeded responses are normalized to USAGE_LIMIT_EXHAUSTED even when the provider used HTTP 401. Check the normalized reason rather than clearing a valid customer session merely because that provider response was 401.

Speech rules can meter requests, characters, audio bytes or duration according to the gateway API matrix. These are distinct measures; use the one your product intends to grant.