{"id":5299,"library":"livekit-plugins-cartesia","title":"LiveKit Agents Plugin for Cartesia","description":"livekit-plugins-cartesia is a Python plugin for LiveKit Agents, providing Text-to-Speech (TTS) and Speech-to-Text (STT) capabilities using Cartesia's AI services. It allows developers to connect directly to Cartesia's API with their own API key, offering an alternative to LiveKit Inference for managing billing and enabling custom Cartesia voices. This library is crucial for building real-time, conversational AI applications that require Cartesia's advanced voice synthesis and transcription.","status":"active","version":"1.5.2","language":"python","source_language":"en","source_url":"https://github.com/livekit/agents","tags":["ai","audio","cartesia","livekit","realtime","voice","tts","stt","plugin"],"install":[{"cmd":"pip install livekit-plugins-cartesia","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This package is a plugin for the LiveKit Agents framework.","package":"livekit-agents","optional":false}],"imports":[{"note":"The Cartesia plugin is imported as a module under livekit.plugins.","symbol":"cartesia","correct":"from livekit.plugins import cartesia"},{"note":"TTS is a class within the cartesia plugin module, not directly under livekit.plugins.","wrong":"from livekit.plugins import TTS","symbol":"TTS","correct":"from livekit.plugins.cartesia import TTS"},{"note":"STT is a class within the cartesia plugin module, not directly under livekit.plugins.","wrong":"from livekit.plugins import STT","symbol":"STT","correct":"from livekit.plugins.cartesia import STT"}],"quickstart":{"code":"import os\nimport asyncio\nfrom livekit.agents import AgentSession, JobContext, WorkerOptions, cli\nfrom livekit.plugins import cartesia\n\nclass CartesiaVoiceAgent:\n    @cli.agent_handler(\"voice\")\n    async def agent_handle(self, ctx: JobContext):\n        session = AgentSession(ctx)\n        await session.start(\n            tts=cartesia.TTS(api_key=os.environ.get('CARTESIA_API_KEY', '')),\n            stt=cartesia.STT(api_key=os.environ.get('CARTESIA_API_KEY', '')),\n            # Other agent components like LLM, VAD, etc., would be configured here\n        )\n\n        print(\"Agent started. Listening for speech...\")\n\n        # Example: Say something to the user\n        await session.say(\"Hello! I am a Cartesia-powered voice agent. How can I help you today?\")\n\n        # In a real agent, you would have a loop to process user input (STT) and generate responses (TTS)\n        # For demonstration, we'll just keep the session alive briefly.\n        await asyncio.sleep(60)\n\n\nif __name__ == \"__main__\":\n    # Ensure environment variables are set for LiveKit and Cartesia\n    # For LiveKit: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET\n    # For Cartesia: CARTESIA_API_KEY\n\n    # Example of how to run the agent (usually via `livekit-cli run`)\n    # For local testing, you might need to set up a mock or local LiveKit server\n    # This quickstart is meant to illustrate the plugin usage, not a full deployment.\n\n    # Set dummy values if env vars are missing for local testing to avoid immediate errors\n    os.environ.setdefault('LIVEKIT_URL', 'wss://your-livekit-server.cloud')\n    os.environ.setdefault('LIVEKIT_API_KEY', 'SK_YOUR_LIVEKIT_API_KEY')\n    os.environ.setdefault('LIVEKIT_API_SECRET', 'YOUR_LIVEKIT_API_SECRET')\n    os.environ.setdefault('CARTESIA_API_KEY', 'YOUR_CARTESIA_API_KEY') # Replace with your actual key\n\n    cli.run(WorkerOptions(agent_handles=[CartesiaVoiceAgent().agent_handle]))","lang":"python","description":"This quickstart demonstrates how to initialize a LiveKit AgentSession with Cartesia's TTS and STT capabilities. It uses `cartesia.TTS` and `cartesia.STT` classes, requiring `CARTESIA_API_KEY` to be set as an environment variable. A full LiveKit Agent setup also requires `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET`."},"warnings":[{"fix":"Refactor `AgentSession` initialization to use the `turn_handling` dictionary for all turn detection and interruption settings, instead of deprecated individual keyword arguments. Refer to the LiveKit Agents 1.5.0 changelog for details.","message":"LiveKit Agents 1.5.0 introduced significant changes to the `TurnHandlingOptions` API. Old keyword arguments for endpointing and interruption (e.g., `min_endpointing_delay`, `allow_interruptions`) are deprecated and will be removed in future versions. Agents should be updated to use the new dictionary-based `turn_handling` parameter.","severity":"breaking","affected_versions":"livekit-agents>=1.5.0"},{"fix":"Ensure `os.environ['CARTESIA_API_KEY']` is set, or pass `api_key='YOUR_CARTESIA_API_KEY'` directly to `cartesia.TTS()` and `cartesia.STT()` during initialization.","message":"The `livekit-plugins-cartesia` plugin requires a Cartesia API key. This key must be provided explicitly to the `TTS` and `STT` constructors or set as the `CARTESIA_API_KEY` environment variable. Without it, Cartesia services will fail to authenticate.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If specific voice characteristics are critical, always explicitly define the `model` and `voice` parameters in `cartesia.TTS()` to ensure consistent behavior across updates. For example, `cartesia.TTS(model='sonic-2', ...)` if you intend to use the older default.","message":"With livekit-agents 1.4.4, the default Cartesia TTS model was upgraded to 'Sonic 3'. If your application previously relied on an older default Cartesia model without explicitly specifying it, the voice output might change unexpectedly after upgrading LiveKit Agents (and by extension, this plugin's underlying dependencies).","severity":"gotcha","affected_versions":"livekit-agents>=1.4.4"}],"env_vars":null,"search_vec":"'advanc':80 'agent':2,16 'ai':33,74,85 'allow':36 'altern':52 'api':44,48 'applic':75 'audio':86 'bill':58 'build':69 'capabl':29 'cartesia':5,9,31,42,62,78,87 'connect':39 'convers':73 'crucial':67 'custom':61 'develop':37 'direct':40 'enabl':60 'infer':55 'key':49 'librari':65 'livekit':1,7,15,54,88 'livekit-plugins-cartesia':6 'manag':57 'offer':50 'plugin':3,8,13,93 'provid':17 'python':12 'real':71 'real-tim':70 'realtim':89 'requir':77 'servic':34 'speech':21,25 'speech-to-text':24 'stt':28,92 'synthesi':82 'text':19,27 'text-to-speech':18 'time':72 'transcript':84 'tts':22,91 'use':30 'voic':63,81,90","created_at":"2026-04-14T01:27:53.951294+00:00","updated_at":"2026-04-16T16:16:11.234404+00:00","problems":[{"fix":"Implement retry logic for STT processing and ensure that STT is only initialized or started after the user has successfully joined the session. The `livekit-agents` framework often handles retries, but delaying the STT start can prevent initial issues.","cause":"This error often occurs due to intermittent network disconnections with the Cartesia API or if STT processing starts before a user has fully joined the LiveKit session, leading to unexpected websocket closures.","error":"livekit.agents._exceptions.APIStatusError: Cartesia STT connection closed unexpectedly"},{"fix":"This can sometimes be transient. Ensure the input text is valid and not empty. If the issue persists, check Cartesia's service status and consider implementing retry mechanisms for TTS synthesis. Updating `livekit-agents` and `livekit-plugins-cartesia` to their latest versions might also help, as patches for this issue have been released.","cause":"This error indicates that the Cartesia TTS plugin failed to synthesize audio for a given text input, often occurring intermittently for valid conversational text.","error":"APIError: no audio frames were pushed"},{"fix":"Verify network connectivity and ensure that the Cartesia API key is correctly configured and has not expired. Also, check that the input text being sent to Cartesia's TTS/STT service is not empty or malformed. Update `livekit-plugins-cartesia` to resolve known issues with empty input text.","cause":"This general connection error can occur if there are network issues preventing communication with the Cartesia API, or if the input text to the TTS/STT service is unexpectedly empty.","error":"livekit.agents._exceptions.APIConnectionError: Connection error."},{"fix":"This is a known issue within `livekit-agents`'s `LogQueueHandler`. A robust fix typically involves sanitizing non-standard attributes in log records before pickling them. Ensure you are using the latest version of `livekit-agents` and `livekit-plugins-cartesia`, as updates may include patches for this logging behavior.","cause":"This `TypeError` occurs in LiveKit Agents when using process-based job execution, specifically when `aiohttp` exceptions (from plugins like Cartesia) are logged. The `CIMultiDictProxy` objects within `aiohttp` response headers are not pickleable, causing the logging process to fail.","error":"TypeError: can't pickle multidict._multidict.CIMultiDictProxy objects"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.7.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://livekit.io/","github":"https://github.com/livekit/agents","docs":"https://docs.livekit.io","changelog":null,"pypi":"https://pypi.org/project/livekit-plugins-cartesia/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}