Last updated 2026-05-17

Cartesia Provider

The cartesia provider implements Speaker (text-to-speech) only. Cartesia's Sonic family is built around real-time conversational synthesis with first-token latencies in the ~40 ms range — choose this provider when end-to-end latency is the critical constraint.

Import path

import (
    "github.com/elloloop/llmrouter"
    "github.com/elloloop/llmrouter/providers/cartesia"
)

Default endpoint

With no WithBaseURL override, the provider targets https://api.cartesia.ai. TTS requests go to {BaseURL}/tts/bytes for non-streaming and {BaseURL}/tts/sse for streaming (SSE).

WebSocket streaming (wss://api.cartesia.ai/tts/websocket) is on the v0.4 roadmap; v0.3 streams via SSE which is sufficient for most server-side pipelines.

Construction

p, err := cartesia.New(
    llmrouter.WithAPIKey(os.Getenv("CARTESIA_API_KEY")),
)
if err != nil {
    log.Fatal(err)
}

Authentication is via the X-API-Key header. Cartesia also requires a Cartesia-Version header pinned to a stable API version; the provider sets a sensible default (currently 2024-11-13) and will be bumped as Cartesia publishes new versions.

Models

• sonic-2 — current production model. 15 languages, sub-100 ms first-token latency, the recommended default.
• sonic-2-2025-03-07 — pinned snapshot of sonic-2. Use this when you need reproducible output.
• sonic-turbo — even lower latency for English-only use cases. Slightly lower quality.

Voice IDs

Cartesia voices are referenced by UUID-shaped IDs. Pass the ID string in SpeechRequest.Voice. A handful of public voice IDs from Cartesia's library (subject to change):

For custom-trained voices, use the voice ID returned by Cartesia's voice-cloning endpoint. The library does not wrap voice management — call the Cartesia REST API directly for that.

Output format mapping

Cartesia uses an output_format object with container, encoding, and sample_rate. The library maps SpeechRequest.Format as follows:

package main

import (
    "context"
    "log"
    "os"

    "github.com/elloloop/llmrouter"
    "github.com/elloloop/llmrouter/providers/cartesia"
)

func main() {
    p, err := cartesia.New(llmrouter.WithAPIKey(os.Getenv("CARTESIA_API_KEY")))
    if err != nil {
        log.Fatal(err)
    }

    stream, err := p.Speak(context.Background(), llmrouter.SpeechRequest{
        Model:  "sonic-2",
        Input:  "Cartesia streams audio with sub-100 millisecond latency.",
        Voice:  "d46abd1d-2d02-43e8-819f-51fb652c1c61",
        Format: "mp3",
        Stream: true,
    })
    if err != nil {
        log.Fatal(err)
    }

    out, _ := os.Create("cartesia.mp3")
    defer out.Close()
    for chunk := range stream.Chunks() {
        out.Write(chunk.Data)
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
    log.Printf("wrote cartesia.mp3 (%s)", stream.ContentType)
}

raw := []byte(`{
  "voice": {
    "mode": "id",
    "id": "d46abd1d-2d02-43e8-819f-51fb652c1c61",
    "__experimental_controls": {
      "emotion": ["positivity:high", "curiosity"],
      "speed": "normal"
    }
  }
}`)

stream, err := p.Speak(ctx, llmrouter.SpeechRequest{
    Model: "sonic-2",
    Input: "What a wonderful evening!",
    Raw:   raw,
})