Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.942s · 35.5MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 4.2s · import 0.864s · 35MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Cartesia
✓ from cartesia import Cartesia
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.
import os
from cartesia import Cartesia
# Ensure CARTESIA_API_KEY environment variable is set
client = Cartesia(
api_key=os.environ.get("CARTESIA_API_KEY", "")
)
try:
response = client.tts.generate(
model_id="sonic-3", # Note: specific models may have deprecation warnings
output_format={
"container": "wav",
"encoding": "pcm_f32le",
"sample_rate": 44100,
},
transcript="I have to say that I'd rather stay awake when I'm asleep.",
voice={
"mode": "id",
"id": "e07c00bc-4134-4eae-9ea4-1a55fb45746b", # Example voice ID
},
)
# In a real application, you might stream this or handle it as bytes
with open("cartesia_generated.wav", "wb") as f:
for chunk in response.iter_bytes():
f.write(chunk)
print("Audio generated and saved to cartesia_generated.wav")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your CARTESIA_API_KEY is set and valid.")
Debug
Known issues
breakingSpecific 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.fixMigrate to newer, supported models like 'sonic-3' or later versions. Refer to the official Cartesia documentation for the latest model availability and recommendations.
affects: All versions
breakingWhen 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`).fixUpdate 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.
affects: Versions 3.0.0 and newer
gotchaAPI 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.fixImplement Access Token generation and management for client-side applications. Ensure server-side applications use API keys securely (e.g., via environment variables).
affects: All versions
breakingThe 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).fixEnsure 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.
affects: All versions (behavior depends on 'Cartesia-Version' header)
gotchaWhile 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.fixReview the `MIGRATING.md` file in the GitHub repository or the official documentation for details on adopting the latest helpers and patterns.
affects: Migrating from 2.x to 3.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cartesia'
The 'cartesia' library is not installed in your Python environment or the Python interpreter cannot locate it in its search path.
fixInstall the library using pip: `pip install cartesia` or `uv add cartesia` if using uv. If you need websocket support, use `pip install 'cartesia[websockets]'`.
cannot import name 'Cartesia' from partially initialized module 'cartesia' (most likely due to a circular import)
This error occurs when your Python script file is named `cartesia.py`, creating a naming conflict with the installed `cartesia` library.
fixRename your script file from `cartesia.py` to something else (e.g., `my_app.py`) to avoid the circular import.
cartesia.AuthenticationError
Your Cartesia API key is either missing, incorrect, expired, or does not have the necessary permissions for the requested operation.
fixEnsure your `CARTESIA_API_KEY` environment variable is correctly set with a valid API key, or pass the `api_key` directly to the `Cartesia` client constructor. You can generate or verify your API key on the Cartesia playground.
cartesia.APIConnectionError
The library was unable to connect to the Cartesia API due to network problems, a timeout, or the API server being unreachable.
fixCheck your internet connection, verify the Cartesia API status, and ensure no firewalls or network configurations are blocking the connection. You can also try increasing the client's timeout setting if network latency is an issue.
cartesia.RateLimitError
You have exceeded the API rate limits for your Cartesia subscription plan, resulting in a 429 Too Many Requests status code from the API.
fixImplement exponential backoff and retry logic in your application to handle rate limits gracefully. Review your usage patterns and consider upgrading your Cartesia subscription plan if you consistently hit rate limits.
Upgrade
Version history
3.2.0latest on PyPI · released May 28, 2026
Audit
Dependencies
websocketsoptionalRequired for streaming inputs and real-time voice applications using websockets.
python-dotenvoptionalCommonly used for loading API keys and other environment variables in local development.