> ## 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エージェントガイド

> 開発者がAIツールを使ってCartesiaを統合するのを支援するための直接的なガイド。

AIアシスタントがCartesiaの統合を支援する場合(**Cursor**、**Claude Code** などの類似ツール)に、このガイドを使用してください。下記のプロンプトをプロジェクトのルールやチャットのコンテキストにコピーするか、[エージェントスキル](/tools/ai/agent-skills) をインストールして同じガイダンスを自動適用してください。

## 何を使うか

以下のツールがすべて必要なわけではありません。APIキーとコピペ用プロンプトから始め、必要に応じて他のものを追加してください。

| やりたいこと                            | 使うもの                                                                           |
| --------------------------------- | ------------------------------------------------------------------------------ |
| AIがCartesiaの統合を支援する               | 下記のプロンプトをコピー **または** [エージェントスキル](/tools/ai/agent-skills) — ルールは同じ。いずれかを選択      |
| アプリをリリースする                        | [クライアントライブラリ](/tools/client-libraries) + [API規約](/use-the-api/api-conventions) |
| エージェントが正しいドキュメントページを見つける          | [`llms.txt`](https://docs.cartesia.ai/llms.txt) — URLをフェッチ; ローカルへのインストールは不要    |
| Cursor または Claude 内でボイス / TTS を試す | [MCP](/tools/ai/mcp) — オプション; 本番環境でのSDKの代替ではありません                              |
| Cartesia Line ボイスエージェントを構築する      | `line-voice-agent` スキル + [Line](/line) ドキュメント                                  |

**エージェントスキル:** 構築しているものに応じて **cartesia-api** および/または **line-voice-agent** をインストールしてください — 「マーケットプレイス上のすべてのスキル」ではありません。[どのスキル?](/tools/ai/agent-skills#which-skill) を参照してください。

## エディタにコピーする

これを **Cursorルール**、**Claude Code** プロジェクト指示、またはCartesia統合スレッドの冒頭に貼り付けてください:

```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
```

## 一般的なパターン

### Web: ボタン → 音声を再生

1. **バックエンド**(APIキー): `Cartesia-Version` と JSON ボディ(`{}` または `{ "grants": { "tts": true } }`)を付けて `POST /access-token` を呼びます。
2. **ブラウザ**(アクセストークン): `Authorization: Bearer <token>`、有効な `model_id`、`voice`、`output_format` を付けて `POST /tts/bytes` を呼びます。
3. レスポンスバイトを `Blob` + `Audio`(またはJS SDK)で再生します。

[ブラウザでの音声再生](/examples/tts-play-audio) および完全な [Next.jsサンプル](/examples/nextjs)(トークンルート + クライアント再生)を参照してください。

## リファレンスリンク

| トピック             | リンク                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| 機械可読ドキュメントインデックス | [`llms.txt`](https://docs.cartesia.ai/llms.txt) · [`llms-full.txt`](https://docs.cartesia.ai/llms-full.txt) |
| API規約            | [API規約](/use-the-api/api-conventions)                                                                       |
| APIキー            | [play.cartesia.ai/keys](https://play.cartesia.ai/keys)                                                      |
| クライアントSDK        | [クライアントライブラリ](/tools/client-libraries)                                                                      |
| ブラウザTTSサンプル      | [ブラウザでの音声再生](/examples/tts-play-audio)                                                                      |
| Next.jsサンプル      | [Next.js完全サンプル](/examples/nextjs)                                                                           |
| MCP              | [MCP](/tools/ai/mcp)                                                                                        |
| エージェントスキル        | [エージェントスキル](/tools/ai/agent-skills)                                                                         |