Cartesia TTS in Node.js and TypeScript
@micdrop/cartesia plugs Cartesia TTS into a @micdrop/server voice agent. It streams the agent’s answer to Cartesia’s Sonic 3 models over a WebSocket, sentence by sentence, and sends the audio back as raw PCM while the LLM is still writing. You pick the model, the voice and one of 44 languages. If you are still choosing a voice engine, you can compare Cartesia and ElevenLabs for a voice agent on latency, voices, price and concurrency.
Installation
npm install @micdrop/cartesiaCartesia TTS (Text-to-Speech)
Usage with MicdropServer
import { CartesiaTTS } from '@micdrop/cartesia'import { MicdropServer } from '@micdrop/server'
const tts = new CartesiaTTS({ apiKey: process.env.CARTESIA_API_KEY || '', modelId: 'sonic-3.6', // Cartesia model ID voiceId: 'a0e99841-438c-4a64-b679-ae501e7d6091', // Voice ID language: 'en', // Optional: specify language sampleRate: 24000, // Optional: 48000 by default generationConfig: { speed: 1.1 }, // Optional: speed, volume and emotion})
// Use with MicdropServernew MicdropServer(socket, { tts, // ... other options})Usage without MicdropServer
import { CartesiaTTS } from '@micdrop/cartesia'import { Readable } from 'stream'
const tts = new CartesiaTTS({ apiKey: process.env.CARTESIA_API_KEY || '', modelId: 'sonic-3.6', voiceId: 'a0e99841-438c-4a64-b679-ae501e7d6091',})
// Audio is raw PCM, 16 bits, mono, at tts.sampleRatetts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))tts.on('Failed', (texts) => console.error('Failed:', texts))
tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))Events
| Event | Payload | Description |
|---|---|---|
Audio | Buffer | A chunk of audio, PCM 16 bits, mono, at tts.sampleRate (the sampleRate option, 48 kHz by default), ready to be played. |
Failed | string[] | Every reconnection attempt failed, with the text that stayed unspoken. The next utterance connects again. |
See the TTS interface for the full contract.
Options
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | Required | Your Cartesia API key |
modelId | string | Required | Cartesia model ID to use, such as sonic-3.6 |
voiceId | string | Required | Voice ID for speech synthesis |
language | CartesiaLanguage | Optional | Language code for speech |
generationConfig | CartesiaGenerationConfig | Optional | Speed, volume and emotion of the voice, see below |
speed | 'fast' | 'normal' | 'slow' | Optional | Deprecated, Sonic 3 models read generationConfig.speed |
sampleRate | CartesiaSampleRate | 48000 | Rate of the audio in Hz: 8000, 16000, 22050, 24000, 44100 or 48000 |
connectionTimeout | number | 5000 | Timeout in milliseconds for WebSocket connection |
retryDelay | number | 1000 | Delay in milliseconds between reconnection attempts |
maxRetry | number | 3 | Number of failed connection attempts in a row before emitting Failed |
Connection
CartesiaTTS keeps one WebSocket open to Cartesia and opens it again whenever it drops, a graceful close included. The sentence under way goes out again on the new connection, unless the user interrupted it in the meantime. After maxRetry failed attempts in a row, it emits Failed, and the next utterance starts a new round of attempts.
Models
CartesiaTTS has no default model, so set modelId in every agent. Use sonic-3.6, the current Sonic model, or pin its snapshot sonic-3.6-2026-08-27 in production. Cartesia stops serving sonic-turbo and sonic-2 after October 20, 2026, so an agent configured with one of them has to switch its modelId before that date. Cartesia lists every model snapshot and its sunset date.
Speed, volume and emotion
generationConfig applies to every sentence the agent speaks. Cartesia treats its values as guidance and keeps the pacing natural.
| Field | Type | Range | Description |
|---|---|---|---|
speed | number | 0.6 to 1.5 | Speech speed, 1 by default |
volume | number | 0.5 to 2.0 | Volume, 1 by default |
emotion | CartesiaEmotion | Emotion the voice leans toward, such as calm or content, English only |
const tts = new CartesiaTTS({ apiKey: process.env.CARTESIA_API_KEY || '', modelId: 'sonic-3.6', voiceId: 'a0e99841-438c-4a64-b679-ae501e7d6091', generationConfig: { speed: 0.9, volume: 1.2, emotion: 'calm' },})To change the tone sentence by sentence, the LLM can write Cartesia’s emotion and speed tags into its answer, such as <emotion value="calm"/>.
Voices
Set voiceId to the UUID of a Cartesia voice, such as a0e99841-438c-4a64-b679-ae501e7d6091. CartesiaTTS.listVoices() returns the voices the account can use, its own and the public ones:
const voices = await CartesiaTTS.listVoices({ apiKey: process.env.CARTESIA_API_KEY || '',})// [{ id, name, languages, gender, description, custom }, ...]Pass language, such as fr or fr-FR, to keep the voices that speak it, every locale of the language included. The list is fetched once, then shared by every call of the process for a day. Pass refresh: true to fetch it again, after adding a voice to the account.
You can also listen to the voices and copy their IDs in the Cartesia voice library, or list them from the API with a language filter:
curl "https://api.cartesia.ai/voices?language=fr&limit=20" \ -H "Authorization: Bearer $CARTESIA_API_KEY" \ -H "Cartesia-Version: 2026-08-14"The response lists the accents of each voice and marks one of them as native. Pick a voice native to the language you set in language, so the agent sounds like a native speaker. To narrow the list, filter on gender, or pass q to search voice names and descriptions.
Supported Languages
Sonic 3.6 speaks 44 languages:
| Code | Language | Code | Language | Code | Language |
|---|---|---|---|---|---|
en | English | fr | French | de | German |
es | Spanish | pt | Portuguese | zh | Chinese |
ja | Japanese | hi | Hindi | it | Italian |
ko | Korean | nl | Dutch | pl | Polish |
ru | Russian | sv | Swedish | tr | Turkish |
tl | Tagalog | bg | Bulgarian | ro | Romanian |
ar | Arabic | cs | Czech | el | Greek |
fi | Finnish | hr | Croatian | ms | Malay |
sk | Slovak | da | Danish | ta | Tamil |
uk | Ukrainian | hu | Hungarian | no | Norwegian |
vi | Vietnamese | bn | Bengali | th | Thai |
he | Hebrew | ka | Georgian | id | Indonesian |
te | Telugu | gu | Gujarati | kn | Kannada |
ml | Malayalam | mr | Marathi | pa | Punjabi |
or | Odia | ur | Urdu |
Getting Started
- Sign up for a Cartesia account and get your API key. The free plan includes 20,000 credits a month at one credit per character, enough to test an agent.
- Choose a model ID and a voice ID
- Install the package and configure with your credentials
import { CartesiaTTS } from '@micdrop/cartesia'
const tts = new CartesiaTTS({ apiKey: 'your-cartesia-api-key', modelId: 'sonic-3.6', voiceId: 'your-preferred-voice-id', language: 'en',})
// Use with MicdropServernew MicdropServer(socket, { tts, // ... other options})Listing models
CartesiaTTS.listModels() returns the models that speak, with the languages each one reads.
const models = await CartesiaTTS.listModels({ apiKey: process.env.CARTESIA_API_KEY || '',})It returns MicdropModel objects: id, the value the model option takes, then when the provider says it name, description, aliases, languages, reasoning for a model that can reason, and deprecated with its shutdownDate. The list is fetched once, then shared by every call of the process for a day. Pass refresh: true to fetch it again.