> ## 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.

# AI agent guide

> A direct guide for helping developers integrate Cartesia using AI tooling.

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](/tools/ai/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](/tools/ai/agent-skills) — same rules; pick one          |
| Ship an app                              | [Client libraries](/tools/client-libraries) + [API conventions](/use-the-api/api-conventions)       |
| Agent finds the right doc pages          | [`llms.txt`](https://docs.cartesia.ai/llms.txt) — fetch the URL; nothing to install on your machine |
| Try voices / TTS inside Cursor or Claude | [MCP](/tools/ai/mcp) — optional; not a replacement for SDKs in production                           |
| Build Cartesia Line voice agents         | `line-voice-agent` skill + [Line](/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?](/tools/ai/agent-skills#which-skill).

## Copy into your editor

Paste this into **Cursor rules**, **Claude Code** project instructions, or the start of a Cartesia integration thread:

```text theme={null}
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](/examples/tts-play-audio) and the full [Next.js example](/examples/nextjs) (token route + client playback).

## Reference links

| Topic                       | Link                                                                                                        |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Machine-readable docs index | [`llms.txt`](https://docs.cartesia.ai/llms.txt) · [`llms-full.txt`](https://docs.cartesia.ai/llms-full.txt) |
| API conventions             | [API conventions](/use-the-api/api-conventions)                                                             |
| API keys                    | [play.cartesia.ai/keys](https://play.cartesia.ai/keys)                                                      |
| Client SDKs                 | [Client libraries](/tools/client-libraries)                                                                 |
| Browser TTS example         | [Play audio in browser](/examples/tts-play-audio)                                                           |
| Next.js example             | [Next.js full example](/examples/nextjs)                                                                    |
| MCP                         | [MCP](/tools/ai/mcp)                                                                                        |
| Agent Skills                | [Agent skills](/tools/ai/agent-skills)                                                                      |