> ## 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.
# LiveAvatar + Cartesia
> LiveAvatar（HeyGen 提供）のインタラクティブアバターを Cartesia Sonic TTS 音声で発話させる
最終検証日：2026年8月5日
## 概要
このインテグレーションを利用すると、[LiveAvatar](https://docs.liveavatar.com) のアバターに [Cartesia Sonic TTS](/build-with-cartesia/tts-models/latest) の音声で応答させることができます。セッションの [音声設定](https://docs.liveavatar.com/docs/full-mode/voice-settings) で `provider` を `cartesia` に指定すると、アバターが Sonic で発話するようになります。独自の API キーと音声を取り込む方法は [独自の Cartesia 音声を利用する](#use-your-own-cartesia-voices) を参照してください。
## 前提条件
* [app.liveavatar.com/developers](https://app.liveavatar.com/developers) で取得した LiveAvatar API キー
* Node.js 22 以上および pnpm 9 以上
* [Cartesia keys](https://play.cartesia.ai/keys) で取得した Cartesia API キー（`sk_car_...`）— 独自の Cartesia 音声を取り込む場合にのみ必要
## クイックスタート
[LiveAvatar Web SDK](https://github.com/heygen-com/liveavatar-web-sdk) のリポジトリには Next.js のデモアプリが含まれています。自分のスペースを指すように設定し、TTS プロバイダーを Cartesia に切り替えて実行します。
```bash theme={null}
git clone https://github.com/heygen-com/liveavatar-web-sdk.git
cd liveavatar-web-sdk
pnpm install
```
`apps/demo/app/api/secrets.ts` の `API_KEY` を設定します。アバター、音声、コンテキストの各 ID は動作するデモ用ペルソナを指しているため、セッションが動作したら自分の値に差し替えてください。
```typescript theme={null}
export const API_KEY = "your-liveavatar-api-key";
export const API_URL = "https://api.liveavatar.com";
// デフォルトはデモに付属しています。自分のスペースの ID に置き換えてください:
// https://docs.liveavatar.com/docs/full-mode/configuration
export const AVATAR_ID = "dd73ea75-1218-4ef3-92ce-606d5f7fbc0a";
export const VOICE_ID = "c2527536-6d1f-4412-a643-53a3497dada9";
export const CONTEXT_ID = "5b9dba8a-aa31-11f0-a6ee-066a7fa2e369";
export const LANGUAGE = "en";
// サンドボックスセッションはクレジットを消費しません: https://docs.liveavatar.com/docs/sandbox-mode
export const IS_SANDBOX = true;
```
`apps/demo/app/api/start-session/route.ts` のセッショントークンリクエストで、既存の `avatar_persona` オブジェクトの中に `voice_settings` ブロックを追加します。音声のレンダリングに使用する TTS エンジンは `provider` フィールドで選択します。
```typescript theme={null}
const res = await fetch(`${API_URL}/v1/sessions/token`, {
method: "POST",
headers: {
"X-API-KEY": API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "FULL",
avatar_id: AVATAR_ID,
avatar_persona: {
voice_id: VOICE_ID,
context_id: CONTEXT_ID,
language: LANGUAGE,
voice_settings: { // <------- このブロックを追加
provider: "cartesia",
model: "sonic-3.5",
speed: 1.0,
},
},
is_sandbox: IS_SANDBOX,
}),
});
```
このルートは `{ session_token, session_id }` を返し、デモはそれを `@heygen/liveavatar-web-sdk` の `LiveAvatarSession` に渡します。
```bash theme={null}
pnpm build
pnpm demo
```
[http://localhost:3001](http://localhost:3001) を開き、**Full Mode** をクリックしてミュートを解除して話しかけてください。`secrets.ts` の既定の音声 ID に対応する Sonic 音声でアバターが応答します。
`secrets.ts` の音声 ID は LiveAvatar が発行する ID を指しており、これは Cartesia が発行する音声 ID である `provider_voice_id` に対応します。両者は同一の ID ではありませんが、同じ音声を指しています。
## 独自の Cartesia 音声を利用する
Cartesia API キーを LiveAvatar の [secret](https://docs.liveavatar.com/docs/core-concepts/secrets) として登録し、そこに Cartesia 音声を紐付けます。詳しい手順は [Custom TTS Integration](https://docs.liveavatar.com/docs/full-mode/custom-tts) を参照してください。`provider_voice_id` は [Cartesia playground](https://play.cartesia.ai/voices) または [list voices エンドポイント](/api-reference/voices/list) から取得できます。
リクエストで使用する環境変数を設定します。
```bash theme={null}
export LIVEAVATAR_API_KEY="your-liveavatar-api-key"
export CARTESIA_API_KEY="your-cartesia-api-key"
```
```bash theme={null}
curl -X POST https://api.liveavatar.com/v1/secrets \
-H "X-API-KEY: $LIVEAVATAR_API_KEY" \
-H "content-type: application/json" \
-d '{
"secret_type": "CARTESIA_API_KEY",
"secret_value": "'"$CARTESIA_API_KEY"'",
"secret_name": "My Cartesia Key"
}'
```
返される JSON にはシークレットの `id` が含まれます。
```json theme={null}
{"code":1000,"data":{"id":"XXXXXXXX-0239-4180-9acd-XXXXXXXXXXX","secret_name":"My Cartesia Key"},"message":"Secret created successfully"}
```
この ID を Cartesia の音声 ID と併せて渡し、LiveAvatar 音声を作成します。
```bash theme={null}
curl -X POST https://api.liveavatar.com/v1/voices/third_party \
-H "X-API-KEY: $LIVEAVATAR_API_KEY" \
-H "content-type: application/json" \
-d '{
"secret_id": "",
"provider_voice_id": "",
"name": "My Cartesia Voice"
}'
```
レスポンスとして LiveAvatar の `voice_id`（指定した Cartesia の Voice ID とは別物）が返ります。これを `secrets.ts` の `VOICE_ID` として利用します。LiveAvatar はそのセッションの音声を、あなたの Cartesia の認証情報を使って生成します。
紐付いた Cartesia 音声が削除されたり、シークレットが削除されたりすると、取り込んだ音声は動作しなくなります。
## 設定
Cartesia 用の `avatar_persona.voice_settings` フィールド：
| パラメータ | 型 | デフォルト | 説明 |
| ---------- | -------- | ------------- | --------------------------------------------------- |
| `provider` | `string` | — | Cartesia で音声をレンダリングするには `cartesia` を指定します |
| `model` | `string` | `"sonic-3.5"` | `sonic-3.5`、`sonic-3`、`sonic-2`、`sonic-turbo` のいずれか |
| `speed` | `number` | `1` | 発話速度、`0.6`〜`1.5` |
## リソース
* [LiveAvatar voice settings](https://docs.liveavatar.com/docs/full-mode/voice-settings)
* [LiveAvatar custom TTS integration](https://docs.liveavatar.com/docs/full-mode/custom-tts)
* [LiveAvatar create session token API](https://docs.liveavatar.com/api-reference/sessions/create-session-token)
* [LiveAvatar Web SDK](https://github.com/heygen-com/liveavatar-web-sdk)
* [Cartesia Sonic 3.5](/build-with-cartesia/tts-models/latest)
* [Cartesia の音量、速度、感情の制御](/build-with-cartesia/capability-guides/volume-speed-emotion)