{"id":5872,"library":"cartesia","title":"Cartesia Python API Library","description":"The official Python library for the Cartesia API, providing convenient access to its REST API from any Python 3.9+ application. It focuses on AI voice capabilities such as Text-to-Speech (TTS), Speech-to-Text (STT), and building real-time voice agents. The library includes comprehensive type definitions, offers both synchronous and asynchronous clients, and supports websockets. It is under active development, with frequent updates and a current stable version of 3.0.2.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/cartesia-ai/cartesia-python","tags":["AI","TTS","Voice","API Client","Text-to-Speech","Speech-to-Text","Async"],"install":[{"cmd":"pip install cartesia","lang":"bash","label":"Basic Installation"},{"cmd":"pip install 'cartesia[websockets]'","lang":"bash","label":"With Websocket Support"}],"dependencies":[{"reason":"Required for streaming inputs and real-time voice applications using websockets.","package":"websockets","optional":true},{"reason":"Commonly used for loading API keys and other environment variables in local development.","package":"python-dotenv","optional":true}],"imports":[{"symbol":"Cartesia","correct":"from cartesia import Cartesia"}],"quickstart":{"code":"import os\nfrom cartesia import Cartesia\n\n# Ensure CARTESIA_API_KEY environment variable is set\nclient = Cartesia(\n    api_key=os.environ.get(\"CARTESIA_API_KEY\", \"\")\n)\n\ntry:\n    response = client.tts.generate(\n        model_id=\"sonic-3\", # Note: specific models may have deprecation warnings\n        output_format={\n            \"container\": \"wav\",\n            \"encoding\": \"pcm_f32le\",\n            \"sample_rate\": 44100,\n        },\n        transcript=\"I have to say that I'd rather stay awake when I'm asleep.\",\n        voice={\n            \"mode\": \"id\",\n            \"id\": \"e07c00bc-4134-4eae-9ea4-1a55fb45746b\", # Example voice ID\n        },\n    )\n\n    # In a real application, you might stream this or handle it as bytes\n    with open(\"cartesia_generated.wav\", \"wb\") as f:\n        for chunk in response.iter_bytes():\n            f.write(chunk)\n    print(\"Audio generated and saved to cartesia_generated.wav\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your CARTESIA_API_KEY is set and valid.\")","lang":"python","description":"This quickstart demonstrates how to initialize the Cartesia client using an API key from an environment variable and generate text-to-speech audio, saving it to a WAV file. It uses the `client.tts.generate` method for basic synchronous audio generation."},"warnings":[{"fix":"Migrate to newer, supported models like 'sonic-3' or later versions. Refer to the official Cartesia documentation for the latest model availability and recommendations.","message":"Specific older text-to-speech models and snapshots (e.g., 'sonic', 'sonic-english', certain 'sonic-2' snapshots) are scheduled for deprecation and discontinuation effective June 1, 2026. Using these models after this date will fail.","severity":"breaking","affected_versions":"All versions"},{"fix":"Update your model IDs to include the specific date snapshot as required by the API. Consult the Cartesia documentation for the correct dated IDs for PVC voices.","message":"When using Pro Voice Cloning (PVC) models, routing now requires dated model IDs (e.g., `sonic-3-2026-01-12`) instead of generic IDs (`sonic-3`).","severity":"breaking","affected_versions":"Versions 3.0.0 and newer"},{"fix":"Implement Access Token generation and management for client-side applications. Ensure server-side applications use API keys securely (e.g., via environment variables).","message":"API key usage differs for client-side vs. server-side applications. For client-side contexts (e.g., web apps), use Access Tokens for enhanced security to avoid exposing your API key. For trusted server-side applications, local scripts, or notebooks, direct API key usage is acceptable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your API requests specify the `Cartesia-Version: 2026-03-01` header to receive structured JSON error responses. Update your error handling logic to parse the new format.","message":"The format for API error responses changed with `Cartesia-Version: 2026-03-01`. Newer requests return structured JSON errors, while older API versions (before 2026-03-01) return legacy error formats (e.g., HTTP Title: Message).","severity":"breaking","affected_versions":"All versions (behavior depends on 'Cartesia-Version' header)"},{"fix":"Review the `MIGRATING.md` file in the GitHub repository or the official documentation for details on adopting the latest helpers and patterns.","message":"While the 3.x series of the Python SDK maintains backwards compatibility with method signatures from 2.x, some new helper functions or improved patterns might require minor code adjustments to leverage the latest features and best practices.","severity":"gotcha","affected_versions":"Migrating from 2.x to 3.x"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}