cartesia

1# Cartesia
2 
3## Purpose
4Generate spoken audio from text with Cartesia's Sonic models (40+ languages) and browse the Cartesia voice library. Reach for this when the user wants narration, voiceovers, or spoken-audio files produced from a script.
5 
6## Tooling
7All commands go through `bin/cartesia.py`. Every request automatically sends the required date header `Cartesia-Version: 2026-08-14`.
8 
9```bash
10bin/cartesia.py auth
11# {"ok": true, "voices": 60} on success
12 
13bin/cartesia.py voices
14# list available voices (id, name, language)
15 
16bin/cartesia.py voice-get --id <VOICE_ID>
17# details for a single voice
18 
19bin/cartesia.py tts --text "Hello world" --voice-id <VOICE_ID> --out narration.wav
20# synthesize speech to a local WAV file; prints the saved path
21 
22bin/cartesia.py tts --text "Bonjour le monde" --voice-id <VOICE_ID> \
23    --language fr --model-id sonic-3 --out fr.wav
24```
25 
26Notes:
27- `tts` returns audio binary. The CLI writes it to `--out` (default `cartesia-output.wav`) and prints the resulting path.
28- Streaming TTS (`POST /tts/sse`) and the WebSocket TTS/STT surfaces are real-time and outside CLI scope.
29 
30## Auth
31- Provider id: `cartesia` (credential is collected as `custom.cartesia`)
32- Collection: Cartesia API key (`sk_car_...`) via the secure credential flow (`credentials.request_api_access`); create one at play.cartesia.ai/keys
33- Allowed hosts: `api.cartesia.ai`
34- Connect placement: `bearer_header` (the key goes in `Authorization: Bearer <key>`)
35…