LiveAvatar + Cartesia Line

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

概要

このインテグレーションを利用すると、デプロイ済みの Cartesia Line エージェントの前段にストリーミング型 LiveAvatar アバターを配置できます。プロンプト、ツール、音声、ターンテイキングは Line エージェントが担当し、LiveAvatar の Cartesia Agent Connector がブリッジを実行し、エージェントの音声からリップシンク済みの映像をレンダリングします。セッション作成時に agent_id と保存済みの Cartesia API キーを渡すだけで、自前の音声パイプラインは不要です。

前提条件

agent_id を持つデプロイ済みの Cartesia Line エージェント（Line クイックスタート。エージェント一覧は play.cartesia.ai/agents）
Cartesia keys で取得した Cartesia API キー（sk_car_...）
app.liveavatar.com/developers で取得した LiveAvatar API キー
Node.js 22 以上および pnpm 9 以上

クイックスタート

LiveAvatar Web SDK のリポジトリには、LITE Mode 用のセッションルートを含む Next.js のデモアプリが付属しています。このルートに Cartesia エージェントの設定を追加して実行します。

Cartesia API キーを LiveAvatar に保存する

LiveAvatar はキーを参照として保持します。したがってセッションリクエストではキー本体ではなく secret_id を渡します。リクエストで使用する環境変数を設定します。

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": "Cartesia Agent Key"
  }'

レスポンスとして id が返ります。次のステップで secret_id として使用します。

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 を設定します。デモには動作する AVATAR_ID が同梱されているため、後で自身のアバターの ID に差し替えてください。

export const API_KEY = "your-liveavatar-api-key";
export const API_URL = "https://api.liveavatar.com";
export const AVATAR_ID = "dd73ea75-1218-4ef3-92ce-606d5f7fbc0a";

// サンドボックスセッションはクレジットを消費しません: https://docs.liveavatar.com/docs/sandbox-mode
export const IS_SANDBOX = true;

LITE セッションを Line エージェントに向ける

apps/demo/app/api/start-lite-session/route.ts のセッショントークンリクエストに cartesia_agent_config を追加します。

import { API_KEY, API_URL, AVATAR_ID, IS_SANDBOX } from "../secrets";

const CARTESIA_SECRET_ID = "your-liveavatar-secret-id";
const CARTESIA_AGENT_ID = "your-cartesia-agent-id";

export async function POST() {
  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: "LITE",
      avatar_id: AVATAR_ID,
      is_sandbox: IS_SANDBOX,
      cartesia_agent_config: {
        secret_id: CARTESIA_SECRET_ID,
        agent_id: CARTESIA_AGENT_ID,
      },
    }),
  });

  if (!res.ok) {
    return new Response(
      JSON.stringify({ error: "Failed to retrieve session token" }),
      { status: res.status },
    );
  }

  const { data } = await res.json();
  return new Response(
    JSON.stringify({
      session_token: data.session_token,
      session_id: data.session_id,
    }),
    { status: 200, headers: { "Content-Type": "application/json" } },
  );
}

secret_id と agent_id はどちらも必須です。LiveAvatar は LiveKit のルームをプロビジョニングし、Line エージェントと通信するワーカーをディスパッチします。

デモを実行する

pnpm build
pnpm demo

http://localhost:3001 を開き、Lite Mode をクリックしてミュートを解除して話しかけてください。Line エージェントが応答し、その音声にアバターがリップシンクします。

セッションイベント

Cartesia コネクター経由のセッションは、LITE Mode の WebSocket イベントではなく、LiveAvatar の FULL Mode イベントシステムを LiveKit のデータチャネル上で使用します。LiveAvatarSession はこれらを型付きのイベントとして発火します。以下のコードは ES モジュール内（たとえばデモアプリの "use client" モジュール）で実行するか、本体を非同期関数でラップしてください。このスニペットはトップレベル await を使用しています。

import {
  AgentEventsEnum,
  LiveAvatarSession,
} from "@heygen/liveavatar-web-sdk";

// sessionToken は start-lite-session ルートのレスポンスから取得します
const session = new LiveAvatarSession(sessionToken, { voiceChat: true });

session.on(AgentEventsEnum.USER_TRANSCRIPTION, ({ text }) => {
  console.log("user:", text);
});

session.on(AgentEventsEnum.AVATAR_TRANSCRIPTION, ({ text }) => {
  console.log("agent:", text);
});

// Line エージェントが通話を終了すると stop_reason "AGENT_HANG_UP" で発火します。
session.on(AgentEventsEnum.SESSION_STOPPED, ({ stop_reason }) => {
  console.log("session stopped:", stop_reason);
});

await session.start();

設定

create session token リクエストの cartesia_agent_config フィールド：

パラメータ	型	デフォルト	説明
`secret_id`	`string`	—	`CARTESIA_API_KEY` を保持する LiveAvatar のシークレット
`agent_id`	`string`	—	接続先の Cartesia Line エージェント

Line エージェントが自身の音声、プロンプト、言語を保持するため、LiveAvatar 側からのセッション単位の上書きはありません。設定をサーバー側に保持したい場合は、cartesia_agent タイプの voice agent として一度保存し、id で参照する方法もあります。ペイロードの詳細はコネクターのドキュメントを参照してください。

​概要

​前提条件

​クイックスタート

Cartesia API キーを LiveAvatar に保存する

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

LiveAvatar API キーを設定する

LITE セッションを Line エージェントに向ける

デモを実行する

​セッションイベント

​設定

​リソース

概要

前提条件

クイックスタート

セッションイベント

設定

リソース