LiveAvatar + Cartesia - Cartesia Docs

最終検証日：2026年8月5日

概要

このインテグレーションを利用すると、LiveAvatar のアバターに Cartesia Sonic TTS の音声で応答させることができます。セッションの音声設定で provider を cartesia に指定すると、アバターが Sonic で発話するようになります。独自の API キーと音声を取り込む方法は独自の Cartesia 音声を利用するを参照してください。

前提条件

app.liveavatar.com/developers で取得した LiveAvatar API キー
Node.js 22 以上および pnpm 9 以上
Cartesia keys で取得した Cartesia API キー（sk_car_...）— 独自の Cartesia 音声を取り込む場合にのみ必要

クイックスタート

LiveAvatar Web SDK のリポジトリには Next.js のデモアプリが含まれています。自分のスペースを指すように設定し、TTS プロバイダーを Cartesia に切り替えて実行します。

SDK リポジトリをクローンしてインストールする

git clone https://github.com/heygen-com/liveavatar-web-sdk.git
cd liveavatar-web-sdk
pnpm install

LiveAvatar API キーを設定する

apps/demo/app/api/secrets.ts の API_KEY を設定します。アバター、音声、コンテキストの各 ID は動作するデモ用ペルソナを指しているため、セッションが動作したら自分の値に差し替えてください。

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;

TTS プロバイダーとして Cartesia を指定する

apps/demo/app/api/start-session/route.ts のセッショントークンリクエストで、既存の avatar_persona オブジェクトの中に voice_settings ブロックを追加します。音声のレンダリングに使用する TTS エンジンは provider フィールドで選択します。

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 に渡します。

デモを実行する

pnpm build
pnpm demo

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 として登録し、そこに Cartesia 音声を紐付けます。詳しい手順は Custom TTS Integration を参照してください。provider_voice_id は Cartesia playground または list voices エンドポイントから取得できます。リクエストで使用する環境変数を設定します。

export LIVEAVATAR_API_KEY="your-liveavatar-api-key"
export CARTESIA_API_KEY="your-cartesia-api-key"

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 が含まれます。

{"code":1000,"data":{"id":"XXXXXXXX-0239-4180-9acd-XXXXXXXXXXX","secret_name":"My Cartesia Key"},"message":"Secret created successfully"}

この ID を Cartesia の音声 ID と併せて渡し、LiveAvatar 音声を作成します。

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": "<secret_id>",
    "provider_voice_id": "<cartesia_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`

​概要

​前提条件

​クイックスタート

SDK リポジトリをクローンしてインストールする

LiveAvatar API キーを設定する

TTS プロバイダーとして Cartesia を指定する

デモを実行する

​独自の Cartesia 音声を利用する

​設定

​リソース

概要

前提条件

クイックスタート

独自の Cartesia 音声を利用する

設定

リソース