# Cartesia

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

## 1. Install

```sh
npm i @tanstack/ai @tanstack/ai-cartesia
```

## 2. Set the API key

Put your Cartesia key in the environment of your server:

```bash
CARTESIA_API_KEY=sk_car_...
```

## 3. Generate speech

Pass a [Cartesia voice ID](https://docs.cartesia.ai/build-with-cartesia/tts-models/latest#voice-selection) to `generateSpeech()`. The result contains base64 audio in MP3 format by default.

```typescript
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`.

```typescript
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](../media/text-to-speech) and [Transcription](../media/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()`.
