Skip to content

Cartesia

Call cartesiaSpeech() to generate audio with Sonic, or call cartesiaTranscription() to transcribe a recording with Ink Whisper.

1. Install

shell
npm i @tanstack/ai @tanstack/ai-cartesia

2. Set the API key

Put your Cartesia key in the environment of your server:

shell
CARTESIA_API_KEY=sk_car_...

3. Generate speech

Pass a Cartesia voice ID to generateSpeech(). The result contains base64 audio in MP3 format by default.

ts
import { generateSpeech } from '@tanstack/ai'
import { cartesiaSpeech } from '@tanstack/ai-cartesia'

const result = await generateSpeech({
  adapter: cartesiaSpeech('sonic-3.6'),
  text: 'Hello from Cartesia.',
  voice: 'db6b0ed5-d5d3-463d-ae85-518a07d3c2b4',
  threadId: 'speech-demo',
})

console.log(result.format, result.contentType)

Set format to mp3, wav, or pcm. pcm audio is mono pcm_s16le at 44100 Hz and has no header.

speed on generateSpeech() sets the speaking rate. Valid values are from 0.6 to 1.5. Values outside that range throw before the request.

modelOptions.volume sets the loudness. Valid values are from 0.5 to 2. Values outside that range throw before the request.

Use modelOptions for language, normalization, and pronunciationDictId.

4. Transcribe a recording

cartesiaTranscription() accepts an audio file, a Blob, an ArrayBuffer, or a base64 string. Use responseFormat: 'verbose_json' to request word timestamps.

If you omit language, Cartesia uses English and translates other speech into English. When the recording is not English, pass language.

ts
import { readFile } from 'node:fs/promises'
import { generateTranscription } from '@tanstack/ai'
import { cartesiaTranscription } from '@tanstack/ai-cartesia'

const bytes = await readFile('./recording.mp3')
const audio = new File([bytes], 'recording.mp3', { type: 'audio/mpeg' })

const result = await generateTranscription({
  adapter: cartesiaTranscription('ink-whisper'),
  audio,
  responseFormat: 'verbose_json',
  threadId: 'transcription-demo',
})

console.log(result.text, result.words)

For browser input and server routes, see Text-to-Speech and Transcription. The Text-to-Speech page includes a Cartesia route. The main Transcription sample uses OpenAI.

For Cartesia, call cartesiaSpeech or cartesiaTranscription. Set CARTESIA_API_KEY on the server. Pass a Cartesia voice id to generateSpeech().