Skip to main content
View as MarkdownOpen in ChatGPTOpen in Claude

Cartesia Provider

Cartesia provides low-latency text-to-speech (Sonic) and both batch and realtime speech-to-text (Ink) models. It does not offer language, embedding, or image models — LanguageModel, EmbeddingModel, and ImageModel all return errors.

Setup​

Installation​

import (
    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/cartesia"
)

Configuration​

provider := cartesia.New(cartesia.Config{
    APIKey: os.Getenv("CARTESIA_API_KEY"),
})

cartesia.Config also accepts BaseURL (default https://api.cartesia.ai) and APIVersion (sent as the Cartesia-Version header, default "2026-03-01").

Get API Key​

export CARTESIA_API_KEY=...

Speech Synthesis​

speechModel, err := provider.SpeechModel(cartesia.ModelSonic2)
if err != nil {
    log.Fatal(err)
}

result, err := ai.GenerateSpeech(ctx, ai.GenerateSpeechOptions{
    Model: speechModel,
    Text:  "Hello from Cartesia.",
    ProviderOptions: map[string]interface{}{
        "cartesia": map[string]interface{}{
            "container":  "mp3",
            "sampleRate": 44100,
            "speed":      1.0,
        },
    },
})

Model IDs: cartesia.ModelSonic35 (sonic-3.5), ModelSonic3 (sonic-3), ModelSonic2 (sonic-2), ModelSonicTurbo (sonic-turbo), ModelSonicLatest (sonic-latest).

Transcription​

transcriptionModel, err := provider.TranscriptionModel(cartesia.ModelInkWhisper)
if err != nil {
    log.Fatal(err)
}

result, err := ai.Transcribe(ctx, ai.TranscribeOptions{
    Model: transcriptionModel,
    Audio: audioBytes,
    ProviderOptions: map[string]interface{}{
        "cartesia": map[string]interface{}{
            "language": "en",
        },
    },
})

Streaming Transcription (Ink 2)​

cartesia.ModelInk2 (and any ink-2-* variant) is streaming-only — the batch DoTranscribe path rejects it. Use ai.ExperimentalStreamTranscribe instead, which streams over Cartesia's Ink 2 WebSocket:

liveModel, err := provider.TranscriptionModel(cartesia.ModelInk2)
if err != nil {
    log.Fatal(err)
}

stream, err := ai.ExperimentalStreamTranscribe(ctx, ai.StreamTranscribeOptions{
    Model: liveModel,
    Audio: audioStream,
    ProviderOptions: map[string]interface{}{
        "cartesia": map[string]interface{}{
            "streaming": map[string]interface{}{
                "turnDetection": true,
            },
        },
    },
})

Provider Options​

OptionApplies toTypeDescription
containerSpeechstringOutput audio container: raw, wav, or mp3
encodingSpeechstringpcm_f32le, pcm_s16le, pcm_mulaw, or pcm_alaw
sampleRateSpeechintOutput sample rate in Hz
bitRateSpeechintBitrate for mp3 output
speedSpeechfloat64Speech speed, 0.6 to 1.5
languageSpeech, TranscriptionstringISO 639-1 language code
timestampGranularitiesTranscription[]stringCurrently only ["word"] is supported
streaming.encodingTranscription (streaming)stringRaw audio encoding sent to Ink 2
streaming.turnDetectionTranscription (streaming)*boolUse Cartesia's native turn detection (default true)

Workflow Serialization​

Cartesia speech and transcription models can cross a workflow boundary with provider.SerializeSpeechModel / DeserializeSpeechModel and provider.SerializeTranscriptionModel / DeserializeTranscriptionModel. See Provider Serialization for the mechanism.

See Also​