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.

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.

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-2`,
  [`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 rate limit for Cartesia has been reached.
• 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.