Documentation Index
Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
Use this file to discover all available pages before exploring further.
Use this guide when an AI assistant helps you integrate Cartesia—Cursor, Claude Code, and similar tools. Copy the prompt below into project rules or chat context, or install Agent skills for the same guidance automatically.
What to use
You do not need every tool below. Start with an API key and the copy-paste prompt; add the rest when they help.
| If you want to… | Use |
|---|
| AI helps you integrate Cartesia | Copy the prompt below or Agent Skills — same rules; pick one |
| Ship an app | Client libraries + API conventions |
| Agent finds the right doc pages | llms.txt — fetch the URL; nothing to install on your machine |
| Try voices / TTS inside Cursor or Claude | MCP — optional; not a replacement for SDKs in production |
| Build Cartesia Line voice agents | line-voice-agent skill + Line docs |
Copy into your editor
Paste this into Cursor rules, Claude Code project instructions, or the start of a Cartesia integration thread:
You are helping a developer integrate Cartesia (Sonic TTS, Ink STT, voices, and related APIs).
Rules (required):
1. Fetch https://docs.cartesia.ai/llms.txt before guessing endpoints, parameters, or examples. Do not invent API fields or voice IDs.
2. Follow https://docs.cartesia.ai/use-the-api/api-conventions — send Cartesia-Version on every request.
3. Base URL: https://api.cartesia.ai (WebSockets: wss://). HTTPS only.
4. Default Cartesia-Version: 2026-03-01 unless the user specifies another date they tested with. On browser WebSockets, use ?cartesia_version=... (query wins over header when both are set).
5. Server/backend: Authorization: Bearer <api_key>. Create keys at https://play.cartesia.ai/keys
6. Browser/mobile: never embed API keys. Backend mints a short-lived access token (POST /access-token with a JSON body — {} or {"grants":{"tts":true}} — see https://docs.cartesia.ai/get-started/authenticate-your-client-applications). Client calls Cartesia with Authorization: Bearer <access_token> (or ?access_token= on WebSockets).
7. Web “button → hear audio”: backend access-token endpoint → browser POST /tts/bytes with the token → response blob → Audio.play(). Examples: https://docs.cartesia.ai/examples/tts-play-audio and https://docs.cartesia.ai/examples/nextjs
8. Prefer official SDKs for app code: https://github.com/cartesia-ai/cartesia-python and https://github.com/cartesia-ai/cartesia-js
9. Sonic speed, volume, emotion: use generation_config (e.g. generation_config.speed), not deprecated top-level speed on REST payloads — https://docs.cartesia.ai/build-with-cartesia/capability-guides/volume-speed-emotion
10. Errors: for Cartesia-Version 2026-03-01 and newer, expect structured JSON — https://docs.cartesia.ai/use-the-api/api-errors
11. Cartesia Line (deployed voice agents, cartesia deploy, telephony) is a separate product — https://docs.cartesia.ai/line — not the same as calling TTS/STT REST APIs from the user's server.
12. CORS: browsers can call https://api.cartesia.ai directly with an access token in typical setups; proxy TTS through the user's backend if the client cannot reach Cartesia (corporate network, custom security policy, etc.).
Optional (often works better in the IDE):
- MCP (Cursor, Claude Desktop, etc.): https://docs.cartesia.ai/tools/ai/mcp — list voices, TTS/STT, dictionaries without custom scripts.
- Agent skills: run `npx skills add cartesia-ai/skills` and choose cartesia-api and/or line-voice-agent — https://docs.cartesia.ai/tools/ai/agent-skills
Common patterns
- Backend (API key):
POST /access-token with Cartesia-Version and a JSON body ({} or { "grants": { "tts": true } }).
- Browser (access token):
POST /tts/bytes with Authorization: Bearer <token>, valid model_id, voice, and output_format.
- Play the response bytes with
Blob + Audio (or the JS SDK).
See Play audio in browser and the full Next.js example (token route + client playback).
Reference links
