Cartesia Tts

Cartesia Text-to-Speech Skill

Ultra-low latency TTS via Cartesia Sonic-3. ~90ms first-byte streaming, 40+ languages, 60+ emotion controls.

Capabilities

Authentication

All requests require a Cartesia API key:

export CARTESIA_API_KEY="your-api-key"

REST header: X-API-Key: $CARTESIA_API_KEY (or Authorization: Bearer $CARTESIA_API_KEY) Cartesia-Version header: Cartesia-Version: 2024-06-10 WebSocket: Pass as query param ?api_key=$CARTESIA_API_KEY&cartesia_version=2024-06-10

Batch TTS (Bytes Endpoint)

Endpoint: POST https://api.cartesia.ai/tts/bytes

Returns complete audio file. Best for generating audio files, batch processing, offline use.

Generate MP3

curl -s -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic",
    "transcript": "Hello, this is a test of Cartesia text to speech.",
    "voice": {"mode": "id", "id": "81db94f2-ea76-4e5a-94bf-c92be997270d"},
    "output_format": {"container": "mp3", "bit_rate": 128000, "sample_rate": 44100}
  }' -o output.mp3

Generate WAV

curl -s -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic",
    "transcript": "Hello, this is a test.",
    "voice": {"mode": "id", "id": "81db94f2-ea76-4e5a-94bf-c92be997270d"},
    "output_format": {"container": "wav", "encoding": "pcm_s16le", "sample_rate": 44100}
  }' -o output.wav

Generate Raw PCM (for streaming pipelines)

curl -s -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic",
    "transcript": "Raw PCM for pipeline processing.",
    "voice": {"mode": "id", "id": "81db94f2-ea76-4e5a-94bf-c92be997270d"},
    "output_format": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 24000}
  }' -o output.raw

Multilingual TTS

curl -s -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic-multilingual",
    "transcript": "Bonjour, ceci est un test en français.",
    "voice": {"mode": "id", "id": "81db94f2-ea76-4e5a-94bf-c92be997270d"},
    "language": "fr",
    "output_format": {"container": "mp3", "bit_rate": 128000, "sample_rate": 44100}
  }' -o output_fr.mp3

Model Selection

Recommendation: Use sonic or sonic-3 for most use cases.

Output Format Options

Container Formats

Encoding Options (for raw and wav)

Sample Rates

Voice Selection

List Available Voices

curl -s "https://api.cartesia.ai/voices" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" | jq '[.[] | select(.language == "en") | {id, name}][:10]'

Voice Specification

{
  "voice": {
    "mode": "id",
    "id": "81db94f2-ea76-4e5a-94bf-c92be997270d"
  }
}

Notable English Voices

Browse all voices: https://play.cartesia.ai/voices

WebSocket Streaming

Endpoint: wss://api.cartesia.ai/tts/websocket

Best for real-time conversational AI, voice assistants, Pipecat pipelines.

Python Example

import asyncio
import websockets
import json
import base64
import os

async def stream_tts():
    """Stream TTS audio via Cartesia WebSocket."""
    api_key = os.environ["CARTESIA_API_KEY"]
    url = f"wss://api.cartesia.ai/tts/websocket?api_key={api_key}&cartesia_version=2024-06-10"

    async with websockets.connect(url) as ws:
        # Send generation request
        request = {
            "model_id": "sonic",
            "transcript": "Hello! This is streaming text to speech from Cartesia.",
            "voice": {"mode": "id", "id": "81db94f2-ea76-4e5a-94bf-c92be997270d"},
            "context_id": "my-context",
            "output_format": {
                "container": "raw",
                "encoding": "pcm_s16le",
                "sample_rate": 24000
            },
            "add_timestamps": True
        }
        await ws.send(json.dumps(request))

        # Receive audio chunks
        audio_chunks = []
        async for msg in ws:
            data = json.loads(msg)
            if data.get("type") == "chunk":
                audio_bytes = base64.b64decode(data["data"])
                audio_chunks.append(audio_bytes)
            elif data.get("type") == "timestamps":
                words = data["word_timestamps"]["words"]
                print(f"Words: {words}")
            elif data.get("type") == "done":
                print("Generation complete")
                break
            elif data.get("type") == "error":
                print(f"Error: {data['error']}")
                break

        # Combine all chunks
        full_audio = b"".join(audio_chunks)
        print(f"Total audio: {len(full_audio)} bytes")
        return full_audio

asyncio.run(stream_tts())

WebSocket Messages

Send — Generation Request:

{
  "model_id": "sonic",
  "transcript": "Text to speak",
  "voice": {"mode": "id", "id": "voice-id"},
  "context_id": "unique-context-id",
  "output_format": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 24000},
  "add_timestamps": true,
  "continue": false
}

Send — Cancel:

{"context_id": "unique-context-id", "cancel": true}

Receive — Audio Chunk:

{"type": "chunk", "data": "base64_pcm_audio", "done": false, "status_code": 206, "step_time": 45, "context_id": "..."}

Receive — Timestamps:

{"type": "timestamps", "word_timestamps": {"words": ["Hello", "world"], "start": [0.0, 0.5], "end": [0.4, 0.9]}, "context_id": "..."}

Receive — Done:

{"type": "done", "done": true, "status_code": 206, "context_id": "..."}

Pipecat Integration

For voice AI pipelines using Pipecat with Cartesia TTS:

from pipecat.services.cartesia import CartesiaTTSService
from pipecat.services.deepgram import DeepgramSTTService
from pipecat.pipeline.pipeline import Pipeline

# Create TTS service for Pipecat pipeline
tts = CartesiaTTSService(
    api_key=os.environ["CARTESIA_API_KEY"],
    voice_id="81db94f2-ea76-4e5a-94bf-c92be997270d",  # Jeff
    model="sonic",
    sample_rate=24000,
    encoding="pcm_s16le",
    container="raw",
)

# Create STT service
stt = DeepgramSTTService(
    api_key=os.environ["DEEPGRAM_API_KEY"],
    params=DeepgramSTTService.InputParams(
        model="nova-3",
        language="en",
        smart_format=True,
        endpointing=300,
        interim_results=True,
    )
)

# Full pipeline: Audio In → STT → LLM → TTS → Audio Out
pipeline = Pipeline([
    transport.input(),
    stt,
    llm,
    tts,
    transport.output(),
])

Pipecat with Emotion Control (Sonic-3)

from pipecat.services.cartesia import CartesiaTTSService

tts = CartesiaTTSService(
    api_key=os.environ["CARTESIA_API_KEY"],
    voice_id="voice-id",
    model="sonic-3",
    params=CartesiaTTSService.InputParams(
        language="en",
        speed=1.0,
        emotion=["excited"],
    )
)

Twilio Telephony + Pipecat + Cartesia

# For phone calls via Twilio SIP → Pipecat → Cartesia TTS
# Use mulaw encoding at 8kHz for telephony
tts = CartesiaTTSService(
    api_key=os.environ["CARTESIA_API_KEY"],
    voice_id="voice-id",
    model="sonic",
    sample_rate=8000,
    encoding="pcm_mulaw",
    container="raw",
)

Request Parameters Reference

Core Parameters

Generation Config (Sonic-3)

Streaming Parameters

Legacy Speed (non-Sonic-3)

Emotion Controls (60+)

Available with Sonic-3 model:

Positive: happy, excited, enthusiastic, elated, euphoric, triumphant, amazed, content, peaceful, serene, calm, grateful, affectionate, proud, confident

Neutral: neutral, curious, contemplative, mysterious, determined

Negative: sad, angry, scared, frustrated, anxious, disappointed, hurt, guilty, bored, tired, rejected, nostalgic, resigned

Social: flirtatious, joking/comedic, sarcastic, ironic, sympathetic, apologetic, hesitant, insecure, skeptical, distant

Supported Languages (40+)

Error Handling

Cost

• Billing: Per character of text synthesized
• Free tier: Available for testing (limited chars/month)
• Pricing: https://cartesia.ai/pricing

Quick Test

# Test TTS generation (generates MP3 of a BDR intro)
curl -s -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic",
    "transcript": "Hi, this is Kaji from Shakudo. We help companies build secure AI systems. Do you have thirty seconds?",
    "voice": {"mode": "id", "id": "81db94f2-ea76-4e5a-94bf-c92be997270d"},
    "output_format": {"container": "mp3", "bit_rate": 128000, "sample_rate": 44100}
  }' -o test.mp3 && ls -la test.mp3

# Expected: MP3 file ~50-150KB with spoken audio
# If you get a file with audio, your API key is working!

# List English voices
curl -s "https://api.cartesia.ai/voices" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2024-06-10" | jq '[.[] | select(.language == "en") | {id, name}][:5]'