Skip to main content
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 CartesiaCopy the prompt below or Agent Skills — same rules; pick one
Ship an appClient libraries + API conventions
Agent finds the right doc pagesllms.txt — fetch the URL; nothing to install on your machine
Try voices / TTS inside Cursor or ClaudeMCP — optional; not a replacement for SDKs in production
Build Cartesia Line voice agentsline-voice-agent skill + Line docs
Agent Skills: install cartesia-api and/or line-voice-agent for what you are building—not “every skill on the marketplace.” See Which skill?.

​
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

​
Web: button → play audio

  1. Backend (API key): POST /access-token with Cartesia-Version and a JSON body ({} or { "grants": { "tts": true } }).
  2. Browser (access token): POST /tts/bytes with Authorization: Bearer <token>, valid model_id, voice, and output_format.
  3. 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).
TopicLink
Machine-readable docs indexllms.txt · llms-full.txt
API conventionsAPI conventions
API keysplay.cartesia.ai/keys
Client SDKsClient libraries
Browser TTS examplePlay audio in browser
Next.js exampleNext.js full example
MCPMCP
Agent SkillsAgent skills