Skip to content

Cartesia Integration

Official Cartesia API Documentation

Cartesia offers a platform for generative audio, including high-quality text-to-speech and voice AI. Use KeyPool to call Cartesia with your team token and a stable base URL.

KeyPool Endpoint for Cartesia

To interact with Cartesia via KeyPool, configure your SDK with the following base URL:

{YOUR_KEYPOOL_BASE_URL}/v1/cartesia

Authentication

Use your KeyPool team token as a bearer token when making requests to the KeyPool Cartesia endpoint.

Do not send a personal Cartesia API key when using KeyPool.

API revision

KeyPool currently pins the upstream Cartesia API revision to 2026-08-14, matching Cartesia SDK 4.2.0's default and Cartesia's API versioning guidance. KeyPool injects this Cartesia-Version header for HTTP requests; caller-supplied values are overridden. For WebSocket requests, KeyPool defaults the cartesia_version query parameter to the same date unless the caller supplies one. This provider API revision is distinct from KeyPool's own service-contract revision.

Free-plan limits

Cartesia's published Free plan uses model credits rather than an LLM-token quota:

Resource Free-plan limit
Model credits 20,000 per month
Sonic 3.6 TTS usage Approximately 27 minutes per month
Concurrent TTS generations 2
Concurrent Ink STT requests 8
TTS WebSocket connections 20 (10× the TTS concurrency limit)

TTS requests beyond two concurrent generations and STT requests beyond eight concurrent requests return 429 Too Many Requests. TTS WebSocket connections are closed after five minutes idle; STT WebSocket connections are closed after three minutes idle. KeyPool retries replayable /tts/bytes requests when Cartesia reports concurrency_limited, but it cannot increase the account's upstream quota.

Cartesia's model credits are not API tokens. Client access tokens are separate short-lived credentials with a maximum lifetime of 3,600 seconds. The Cartesia pricing page and account playground are authoritative for account usage and plan state.

Source: concurrency and WebSocket limits, pricing, and access tokens.

Use sonic-3.6 for the current stable TTS model. ink-2 is the current streaming STT model; ink-whisper remains the batch STT model used by the sample below.

Key Features and Usage

KeyPool supports Cartesia HTTP APIs, including voices, text-to-speech, batch speech-to-text, voice changer, datasets, fine-tunes, pronunciation dictionaries, access tokens, and agent management.

KeyPool spreads Cartesia HTTP traffic across the workspace credential pool with burst-safe random selection. For one-shot HTTP calls such as /tts/bytes, KeyPool retries Cartesia per-key concurrency 429 responses with another credential when the upstream response indicates concurrency_limited or too many concurrent requests. Responses include X-KeyPool-Retry-Count so callers can see whether KeyPool had to retry internally.

Cartesia's WebSocket APIs are also available through KeyPool:

wss://keypool.example.com/v1/cartesia/tts/websocket
wss://keypool.example.com/v1/cartesia/stt/websocket
wss://keypool.example.com/v1/cartesia/agents/stream/{agentId}

For server-side clients, authenticate the WebSocket upgrade with Authorization: Bearer ${KEYPOOL_TOKEN} or another standard KeyPool team-token header. For browser clients that cannot set custom headers, use the generic KeyPool WebSocket auth subprotocol:

const ws = new WebSocket(
  `${KEYPOOL_WS_BASE_URL}/v1/cartesia/tts/websocket?model_id=sonic-3.6`,
  [`keypool-token.${KEYPOOL_TOKEN}`],
)

For browser clients that cannot set custom headers, send the KeyPool token with the keypool-token.<token> WebSocket subprotocol shown above.

1. List Voices

Retrieve a list of available voices from Cartesia.

Python Example:

import os
from cartesia import Cartesia

KEYPOOL_BASE_URL = os.environ.get("KEYPOOL_BASE_URL")
KEYPOOL_TOKEN = os.environ.get("KEYPOOL_TOKEN")

client = Cartesia(
    api_key=KEYPOOL_TOKEN,
    base_url=f"{KEYPOOL_BASE_URL}/v1/cartesia",
)

# Fetch the first page of voices
page = client.voices.list()
voices = list(page)

print("Available Cartesia Voices:")
for voice in voices:
    print(f"- {voice.name} (ID: {voice.id}, Language: {voice.language})")

TypeScript Example:

import Cartesia from "@cartesia/cartesia-js";

const KEYPOOL_BASE_URL = process.env.KEYPOOL_BASE_URL;
const KEYPOOL_TOKEN = process.env.KEYPOOL_TOKEN;

// The Cartesia TypeScript SDK might require a custom fetch implementation
// if it attempts to resolve absolute paths incorrectly with this base URL.
// The example below demonstrates how to configure it.
const client = new Cartesia({
  apiKey: KEYPOOL_TOKEN,
  fetch: (input: RequestInfo | URL, init?: RequestInit) => {
    // This custom fetch ensures SDK requests use the KeyPool service path.
    const PROVIDER_URL_PREFIX = "https://api.cartesia.ai/";
    const KEYPOOL_URL_PREFIX = `${KEYPOOL_BASE_URL}/v1/cartesia/`;

    let rewrittenUrl: string;
    const rawUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;

    if (rawUrl.startsWith(PROVIDER_URL_PREFIX)) {
      rewrittenUrl = `${KEYPOOL_URL_PREFIX}${rawUrl.slice(PROVIDER_URL_PREFIX.length)}`;
    } else {
      rewrittenUrl = `${KEYPOOL_URL_PREFIX}${rawUrl}`;
    }

    return fetch(rewrittenUrl, init);
  },
});

async function listVoices() {
  const page = await client.voices.list({ limit: 5 }); // Fetch a limited number of voices
  console.log("Available Cartesia Voices:");
  page.data.forEach((voice) => {
    console.log(`- ${voice.name} (ID: ${voice.id}, Language: ${voice.language})`);
  });
}

listVoices();

Error Handling

KeyPool handles various error conditions gracefully, providing informative responses. Common error scenarios include:

  • 401 Unauthorized: Invalid or missing KeyPool Team Token.
  • 403 Forbidden: Your Team Token does not have permission to access the Cartesia service.
  • 429 Quota Exceeded: Your team's KeyPool rate limit for Cartesia has been reached. Cartesia per-key concurrency 429s are retried by KeyPool when the request body can be replayed; if all attempted credentials are busy, the final upstream 429 may still be returned.
  • 503 No Available Keys: Cartesia is temporarily unavailable through your KeyPool workspace.
  • 502 Upstream Failed: The request to the Cartesia API failed (e.g., network error, Cartesia API down).

Interactive API Reference

For all Cartesia endpoints and in-browser testing, see API Reference → Cartesia.