你能用 Connect Kit 做什麼？

不到 15 分鐘，一個會說話的 3D 虛擬人就能上線——還有完整的平台供你持續擴展。以下是現在可用的功能，以及即將推出的能力。

// 表演引擎 — 現在就可以用
const presenter = document.querySelector("sv-presenter");

button.addEventListener("click", async () => {
  await presenter.resumeAudioPlayback();
  await presenter.initialize(connectToken, { avatarId, sceneId, voiceId });
  presenter.present("我想要吃早餐。");
});

Connect Kit で何が作れる？

15 分以内にしゃべる 3D アバターをオンラインにできます——さらに必要なだけ拡張できるプラットフォームも揃っています。現在利用可能な機能と近日公開予定の機能をご紹介します。

// プレゼンテーションエンジン — 今すぐ使えます
const presenter = document.querySelector("sv-presenter");

button.addEventListener("click", async () => {
  await presenter.resumeAudioPlayback();
  await presenter.initialize(connectToken, { avatarId, sceneId, voiceId });
  presenter.present("朝ごはんが食べたいです。");
});

什麼是 Perxona Connect Kit？

Connect Kit 是一個可立即執行的 Express + 原生 JS 範例應用程式，展示了 Perxona Presentation Service（Connect API）與 <sv-presenter> Web Component 的完整端到端整合流程。專為黑客松與合作夥伴整合設計——快速 clone、易於閱讀，是起點而非生產就緒應用程式。

主要有兩個部分：

• server.mjs — 使用服務憑證向 Connect API 進行身份驗證的 Express 後端，快取 Bearer Token，並為瀏覽器公開小型代理 API。
• public/demos/basic/app.js — 驅動從 Perxona CDN 載入的 <sv-presenter> Web Component 的零依賴原生 JS 前端。

Perxona Connect Kit とは？

Connect Kit は、Perxona Presentation Service（Connect API）と <sv-presenter> Web コンポーネントのエンドツーエンド統合を示す、すぐに動かせる Express + バニラ JS サンプルアプリです。ハッカソンやパートナー統合向けに設計されており、素早くクローンでき、コードが読みやすく、出発点として使うことを想定しています。

主な構成要素は 2 つです：

• server.mjs — サービス認証情報で Connect API に認証し、Bearer トークンをキャッシュして、ブラウザ向けプロキシ API を提供する Express バックエンド。
• public/demos/basic/app.js — Perxona の CDN から読み込まれた <sv-presenter> Web コンポーネントを操作するゼロ依存のバニラ JS フロントエンド。

取得 API 憑證

在執行 Connect Kit 範例之前，你需要一個 Perxona 帳號。註冊完全自助——無需審核或邀請碼，以下三個步驟約需兩分鐘。

1. 請求 signup token

   將你的 email 傳送至 signup 端點。伺服器回傳 201（無回應內容），並將 純文字 token 寄至你的信箱。

   curl -X POST https://console.perxona.ai/asia/api/v1/connect/auth/signup \
     -H "Content-Type: application/json" \
     -d '{"email": "you@example.com"}'

2. 收信並複製 token

   開啟來自 Perxona 的信件。信中有一段短字串 token—— 不是可點擊的連結。複製這段 token，下一步會用到。

   

3. 完成註冊並設定密碼

   傳入 token、你的 email（作為 username）以及你設定的密碼。 成功後回傳 access_token，帳號即啟用。

   curl -X POST https://console.perxona.ai/asia/api/v1/connect/auth/confirm-signup \
     -H "Content-Type: application/json" \
     -d '{
       "token":    "YOUR_TOKEN_FROM_EMAIL",
       "username": "you@example.com",
       "password": "YourPassword123!"
     }'

   回應：{"access_token": "eyJ..."}。帳號已啟用。

API 認証情報を取得

Connect Kit サンプルを実行する前に、Perxona アカウントが必要です。登録は完全セルフサービス——承認や招待コードは不要です。以下の 3 ステップで約 2 分で完了します。

1. サインアップトークンをリクエスト

   メールアドレスをサインアップエンドポイントに送信します。サーバーは 201（本文なし）を返し、受信トレイに プレーンテキストのトークンを送信します。

   curl -X POST https://console.perxona.ai/asia/api/v1/connect/auth/signup \
     -H "Content-Type: application/json" \
     -d '{"email": "you@example.com"}'

2. メールを確認してトークンをコピー

   Perxona からのメールを開いてください。クリック可能なリンクでは なく、短いトークン文字列が記載されています。 次のステップで使用するのでコピーしてください。

   

3. サインアップを完了してパスワードを設定

   トークン、メールアドレス（username として使用）、 設定するパスワードを送信します。成功すると access_token が返されアカウントが有効になります。

   curl -X POST https://console.perxona.ai/asia/api/v1/connect/auth/confirm-signup \
     -H "Content-Type: application/json" \
     -d '{
       "token":    "YOUR_TOKEN_FROM_EMAIL",
       "username": "you@example.com",
       "password": "YourPassword123!"
     }'

   レスポンス：{"access_token": "eyJ..."}。アカウントが有効になりました。

運作原理

架構

兩個 Demo 共用相同的三層基礎。 <sv-presenter> 是最內層的核心元件——一個 CDN Web Component，直接透過 Connect API 處理語音、動作與口型同步。Demo 以不同的應用層包裝它。

Basic Demo

單頁式虛擬人 presenter。應用程式提供 catalog UI 與文字輸入框，然後以 Connect token 初始化 <sv-presenter>——所有渲染、合成與播放都在元件內部完成。

┌─ Browser ─────────────────────────────────────────────────────┐
│  ┌─ demos/basic/app.js ──────────────────────────────────┐    │
│  │  Catalog pickers · Launch button · Text / audio input │    │
│  │                                                       │    │
│  │  ┌─ <sv-presenter>  (Web Component, CDN) ──────────┐  │    │
│  │  │  Audio synthesis  ·  Motion playback            │  │    │
│  │  │  Lip-sync rendering  ·  Token auto-refresh      │  │    │
│  │  └─────────────────────────────────────────────────┘  │    │
│  └───────────────────────────────────────────────────────┘    │
└───────────────────────────────────────────────────────────────┘
       │  /api/*  (proxy)                   │  direct (bearer token)
       ▼                                    ▼
┌─ server.mjs ────────────┐     ┌─ Connect API ─────────────┐
│  /api/config            │     │  /assets  (catalog)       │
│  /api/connect-token     │────►│  /presentation            │
│  /api/avatars           │     │  /voice-tokens/tts        │
│  /api/scenes            │     └───────────────────────────┘
│  /api/voices            │
│  /api/chat  (opt-in)    │
└─────────────────────────┘

 Browser (app.js)        server.mjs                      Connect API
       │                      │                               │
  1.   ├─ GET /api/config ───►│                               │
       │◄─ presenterUrl ──────┤                               │
  2.   ├─ load <script> from presenterUrl (CDN)               │
       │                      │                               │
  3.   ├─ GET /api/avatars ──►│                               │
       ├─ GET /api/scenes ───►│                               │
       ├─ GET /api/voices ───►│                               │
       │◄─ catalog items ─────┤                               │
  4.   ├─ GET /api/connect-token ────────────────────────────►│
       │◄─ connect_token ─────────────────────────────────────┤
  5.   ├─ presenter.initialize(token, { avatarId, ... }) ────►│
       │◄─ PRESENTER_STATUS: Ready ───────────────────────────┤
  6.   ├─ presenter.present("Hello!") ───────────────────────►│
       │◄─ avatar speaks ─────────────────────────────────────┤

Chatbot Demo

在 Basic 之上新增完整的 chatbot 層。Chatbot Manager 處理 bot CRUD、knowledge file 與 function tools。Chat Panel 驅動多輪對話——每個 AI 回覆直接串接至 <sv-presenter> 即時發話。

┌─ Browser ───────────────────────────────────────────────────────┐
│  ┌─ demos/chatbot/app.js ───────────────────────────────────┐   │
│  │  ┌─ Chatbot Manager ────┐  ┌─ Avatar Stage ─────────┐    │   │
│  │  │  Bot picker (CRUD)   │  │  ┌─ <sv-presenter> ─┐  │    │   │
│  │  │  Knowledge upload    │  │  │  (CDN Component) │  │    │   │
│  │  │  Function tools      │  │  │  initialize()    │  │    │   │
│  │  └──────────────────────┘  │  │  present(reply)  │  │    │   │
│  │                            │  └──────────────────┘  │    │   │
│  │  ┌─ Chat Panel ─────────┐  └────────────────────────┘    │   │
│  │  │  Multi-turn history  │                                │   │
│  │  │  User → AI reply     │                                │   │
│  │  └──────────────────────┘                                │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
       │  /api/*  (proxy)                   │  direct (bearer token)
       ▼                                    ▼
┌─ server.mjs ───────────────────┐  ┌─ Connect API ──────────────┐
│  /api/chatbots  (CRUD)         │  │  /chatbots                 │
│  /api/chatbots/:id/chat        │─►│  /chatbots/:id/chat        │
│  /api/chatbots/:id/knowledge   │  │  /assets · /presentation   │
│  /api/connect-token            │  └────────────────────────────┘
└────────────────────────────────┘

 Browser (app.js)        server.mjs        Connect API
       │                      │                 │
  1-4. ├─ [config → catalog → connect-token → presenter.initialize()]
       │                      │                 │
  5.   ├─ POST /api/chatbots ──────────────────►│ create bot
       │◄─ { id, name, status } ────────────────┤
  6.   ├─ POST /api/chatbots/:id/knowledge ────►│ upload file
       │◄─ { knowledge: { status } } ───────────┤
  7.   ├─ POST /api/chatbots/:id/chat ─────────►│
       │  { messages: [{ role, parts }] }       │ AI response
       │◄─ { reply_text } ──────────────────────┤
  8.   ├─ presenter.present(reply_text) ───────►│
       │◄─ avatar speaks ───────────────────────┤

驗證模型

1. 伺服器從 .env 讀取 PERXONA_CONNECT_EMAIL / PERXONA_CONNECT_PASSWORD。
2. 在第一次請求受保護路由時，伺服器登入並將 Bearer Token 快取在記憶體中。
3. 瀏覽器呼叫 GET /api/connect-token——伺服器驗證並回傳快取的 token。
4. 瀏覽器將 token 傳入 presenter.initialize(connectToken, { avatarId, sceneId, voiceId })。
5. 從此時起，<sv-presenter> 直接與 Connect API 通訊——語音和動作由元件處理，而非伺服器。
6. 若快取的 token 過期（來自上游的 401/403），伺服器會重新登入並重試一次——對瀏覽器透明。

仕組み

アーキテクチャ

両方のデモは同じ 3 層構成を共有しています。 <sv-presenter> は最内層のコアコンポーネント —— Connect API を通じて音声・モーション・リップシンクを直接処理する CDN Web コンポーネントです。デモは用途に応じて異なるアプリケーション層でラップします。

Basic Demo

単一ページのアバター Presenter。アプリはカタログ UI とテキスト入力を提供し、Connect トークンで <sv-presenter> を初期化します——レンダリング・合成・再生はすべてコンポーネント内で行われます。

┌─ Browser ─────────────────────────────────────────────────────┐
│  ┌─ demos/basic/app.js ──────────────────────────────────┐    │
│  │  Catalog pickers · Launch button · Text / audio input │    │
│  │                                                       │    │
│  │  ┌─ <sv-presenter>  (Web Component, CDN) ──────────┐  │    │
│  │  │  Audio synthesis  ·  Motion playback            │  │    │
│  │  │  Lip-sync rendering  ·  Token auto-refresh      │  │    │
│  │  └─────────────────────────────────────────────────┘  │    │
│  └───────────────────────────────────────────────────────┘    │
└───────────────────────────────────────────────────────────────┘
       │  /api/*  (proxy)                   │  direct (bearer token)
       ▼                                    ▼
┌─ server.mjs ────────────┐     ┌─ Connect API ─────────────┐
│  /api/config            │     │  /assets  (catalog)       │
│  /api/connect-token     │────►│  /presentation            │
│  /api/avatars           │     │  /voice-tokens/tts        │
│  /api/scenes            │     └───────────────────────────┘
│  /api/voices            │
│  /api/chat  (opt-in)    │
└─────────────────────────┘

 Browser (app.js)        server.mjs                      Connect API
       │                      │                               │
  1.   ├─ GET /api/config ───►│                               │
       │◄─ presenterUrl ──────┤                               │
  2.   ├─ load <script> from presenterUrl (CDN)               │
       │                      │                               │
  3.   ├─ GET /api/avatars ──►│                               │
       ├─ GET /api/scenes ───►│                               │
       ├─ GET /api/voices ───►│                               │
       │◄─ catalog items ─────┤                               │
  4.   ├─ GET /api/connect-token ────────────────────────────►│
       │◄─ connect_token ─────────────────────────────────────┤
  5.   ├─ presenter.initialize(token, { avatarId, ... }) ────►│
       │◄─ PRESENTER_STATUS: Ready ───────────────────────────┤
  6.   ├─ presenter.present("Hello!") ───────────────────────►│
       │◄─ avatar speaks ─────────────────────────────────────┤

Chatbot Demo

Basic の上に完全なチャットボット層を追加します。Chatbot Manager がボットの CRUD・ナレッジファイル・ファンクションツールを処理します。Chat Panel がマルチターン会話を駆動し、各 AI の返答は直接 <sv-presenter> に渡されてライブで発話されます。

┌─ Browser ───────────────────────────────────────────────────────┐
│  ┌─ demos/chatbot/app.js ───────────────────────────────────┐   │
│  │  ┌─ Chatbot Manager ────┐  ┌─ Avatar Stage ─────────┐    │   │
│  │  │  Bot picker (CRUD)   │  │  ┌─ <sv-presenter> ─┐  │    │   │
│  │  │  Knowledge upload    │  │  │  (CDN Component) │  │    │   │
│  │  │  Function tools      │  │  │  initialize()    │  │    │   │
│  │  └──────────────────────┘  │  │  present(reply)  │  │    │   │
│  │                            │  └──────────────────┘  │    │   │
│  │  ┌─ Chat Panel ─────────┐  └────────────────────────┘    │   │
│  │  │  Multi-turn history  │                                │   │
│  │  │  User → AI reply     │                                │   │
│  │  └──────────────────────┘                                │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
       │  /api/*  (proxy)                   │  direct (bearer token)
       ▼                                    ▼
┌─ server.mjs ───────────────────┐  ┌─ Connect API ──────────────┐
│  /api/chatbots  (CRUD)         │  │  /chatbots                 │
│  /api/chatbots/:id/chat        │─►│  /chatbots/:id/chat        │
│  /api/chatbots/:id/knowledge   │  │  /assets · /presentation   │
│  /api/connect-token            │  └────────────────────────────┘
└────────────────────────────────┘

 Browser (app.js)        server.mjs        Connect API
       │                      │                 │
  1-4. ├─ [config → catalog → connect-token → presenter.initialize()]
       │                      │                 │
  5.   ├─ POST /api/chatbots ──────────────────►│ create bot
       │◄─ { id, name, status } ────────────────┤
  6.   ├─ POST /api/chatbots/:id/knowledge ────►│ upload file
       │◄─ { knowledge: { status } } ───────────┤
  7.   ├─ POST /api/chatbots/:id/chat ─────────►│
       │  { messages: [{ role, parts }] }       │ AI response
       │◄─ { reply_text } ──────────────────────┤
  8.   ├─ presenter.present(reply_text) ───────►│
       │◄─ avatar speaks ───────────────────────┤

認証モデル

1. サーバーが .env から PERXONA_CONNECT_EMAIL / PERXONA_CONNECT_PASSWORD を読み込みます。
2. 保護されたルートへの最初のリクエスト時、サーバーはログインしてメモリに Bearer トークンをキャッシュします。
3. ブラウザが GET /api/connect-token を呼び出し、サーバーはキャッシュしたトークンを検証して返します。
4. ブラウザがトークンを presenter.initialize(connectToken, { avatarId, sceneId, voiceId })に渡します。
5. その後、<sv-presenter> は Connect API と直接通信します——音声とモーションはコンポーネントが処理し、サーバーは関与しません。
6. キャッシュしたトークンが期限切れ（上流から 401/403）の場合、サーバーは再ログインして 1 回リトライします——ブラウザには透過的です。

設定

所有設定透過 .env 進行。將 .env.example 複製為 .env 並填入你的值。絕對不要提交 .env——它已在 .gitignore 中。

設定

すべての設定は .env で行います。.env.example を .env にコピーして値を入力してください。.env は絶対にコミットしないでください——.gitignore に含まれています。

快速開始

範例應用是一個單一的 Node/Express 伺服器，提供兩個可執行的 browser demo，都建立在相同的 <sv-presenter> 整合之上： Presenter——Basic demo：瀏覽 avatar catalog、啟動 presenter 並驅動語音（可選搭配 LLM chat）；以及 Chatbot——完整的 chatbot CRUD、持久多輪對話，以及 knowledge file 與 function tools。伺服器只需啟動一次，即可開啟任一 demo。以下步驟帶你從 clone 到說話的虛擬人。

1. Clone 範例

   git clone https://github.com/XRSPACE-Inc/perxona-connect-kit.git
   cd perxona-connect-kit

2. 建立本機設定檔

   cp .env.example .env

   開啟 .env 並填入三個必填值：

   PERXONA_API_BASE_URL=https://console.perxona.ai/asia
   PERXONA_CONNECT_EMAIL=your@email.com
   PERXONA_CONNECT_PASSWORD=your-password

3. 安裝依賴套件

   npm install

   需要 Node >=22。若版本過舊，npm install 會顯示明確的升級訊息並拒絕執行。

4. 啟動伺服器

   npm run dev    # 啟動並監聽檔案變更
   # 或
   npm start      # 不監聽變更

   終端機會印出本機 URL，例如 http://localhost:8083。

5. 啟動虛擬人

   在瀏覽器開啟該 URL。首頁提供兩個範例—— Basic 與 Chatbot——分別展示不同的產品功能與整合能力。進入任一範例，選擇 Avatar、Scene 和 Voice，點擊 Launch，虛擬人將出現並開始說話。

クイックスタート

サンプルアプリは 1 つの Node/Express サーバーで、同じ <sv-presenter> 統合の上に構築された 2 つの実行可能なブラウザデモを提供します： Presenter——Basic デモ：avatar カタログを閲覧し、presenter を起動して発話を駆動（任意で LLM チャット）；および Chatbot——チャットボットの完全な CRUD、永続的なマルチターン会話、ナレッジファイルと function tools。サーバーを一度起動すれば、どちらのデモも開けます。以下の手順で、クローンからしゃべるアバターまで進めます。

1. サンプルをクローン

   git clone https://github.com/XRSPACE-Inc/perxona-connect-kit.git
   cd perxona-connect-kit

2. ローカル設定ファイルを作成

   cp .env.example .env

   .env を開いて 3 つの必須値を入力してください：

   PERXONA_API_BASE_URL=https://console.perxona.ai/asia
   PERXONA_CONNECT_EMAIL=your@email.com
   PERXONA_CONNECT_PASSWORD=your-password

3. 依存関係をインストール

   npm install

   Node >=22 が必要です。古いバージョンの場合、npm install は明確なアップグレードメッセージとともに失敗します。

4. サーバーを起動

   npm run dev    # ライブリロード (node --watch)
   # または
   npm start      # ウォッチなし

   ターミナルにローカル URL（例：http://localhost:8083）が表示されます。

5. アバターを起動

   ブラウザで URL を開いてください。ランディングページには Basic と Chatbot の 2 つのデモが表示されます——それぞれ異なる製品機能と統合能力を体験できます。どちらかのデモを開き、Avatar・Scene・Voice を選択して Launch をクリックしてください。アバターが表示されてしゃべります。

Presenter

demos/basic/ demo 是每個 Connect 應用都需要的核心 <sv-presenter> 整合，以約 300 行的原生 JS 呈現。它示範四件事：catalog 瀏覽（取得 avatar、scene 與 voice）、presenter 初始化（以伺服器憑證換取 Connect token 並傳給 initialize()）、驅動語音（將文字傳給 present()，或透過 presentWithAudio() 提供自己的音訊），以及可選的 LLM chat，將回覆回傳給 presenter 發話。以下是頁面生命週期：

1. 頁面載入：app.js 呼叫 GET /api/config，從 presenterUrl 動態注入 presenter 引擎 <script>，然後載入 catalog（/api/avatars、/api/scenes、/api/voices）以填充下拉選單。
2. Launch 點擊：呼叫 presenter.resumeAudioPlayback() 解鎖自動播放（必須在點擊處理器中），取得 GET /api/connect-token，然後呼叫 presenter.initialize(connectToken, { avatarId, sceneId, voiceId })。
3. 就緒狀態：presenter 觸發 PRESENTER_STATUS，detail = "Ready"——UI 顯示演出控制項。
4. 播放：預設按鈕和自由文字輸入框呼叫 presenter.present(text)。停止按鈕呼叫 presenter.interruptPresentation()。
5. 聊天（可選）：若設定了 LLM_API_KEY，聊天面板出現。使用者訊息傳送至 POST /api/chat，LLM 回應透過 presenter.present() 發話。

Presenter

demos/basic/ デモは、すべての Connect アプリに必要な基本的な <sv-presenter> 統合を、約 300 行のバニラ JS で示します。次の 4 つを学べます：カタログの閲覧（avatar・scene・voice の取得）、presenter の初期化（サーバー資格情報を Connect トークンと交換し initialize() に渡す）、発話の駆動（テキストを present() に送るか、 presentWithAudio() で独自の音声を提供）、そして任意の LLM チャット（応答を presenter に戻して発話）。ページのライフサイクルは以下の通りです：

1. ページ読み込み：app.js が GET /api/config を呼び出し、presenterUrl から presenter エンジンの <script> を動的に注入し、カタログ（/api/avatars、/api/scenes、/api/voices）を読み込んでドロップダウンを設定します。
2. Launch クリック：presenter.resumeAudioPlayback() を呼び出して自動再生をアンロック（クリックハンドラー内で必須）、GET /api/connect-token を取得し、presenter.initialize(connectToken, { avatarId, sceneId, voiceId }) を呼び出します。
3. 準備完了状態：presenter が detail = "Ready" で PRESENTER_STATUS を発行——UI がパフォーマンスコントロールを表示します。
4. 再生：プリセットボタンとフリーテキスト入力が presenter.present(text) を呼び出します。停止ボタンが presenter.interruptPresentation() を呼び出します。
5. チャット（オプション）：LLM_API_KEY が設定されている場合、チャットパネルが表示されます。ユーザーのメッセージは POST /api/chat に送信され、LLM の応答が presenter.present() で発話されます。

Chatbot

demos/chatbot/ demo 將 Perxona Connect Chatbot API 整合到相同的 <sv-presenter> 舞台上。在 Presenter demo 的基礎上，它新增了完整的 chatbot CRUD、持久的多輪對話，以及 knowledge file 與 function tools。每個助手回覆都會傳入 presenter.present()，讓 avatar 即時發話。訊息使用 Connect 的 parts 格式（{ role, parts: [{ type: 'text', text }] }），並以 20 則訊息的滑動視窗送出以避免上游逾時。開啟 http://localhost:8083/demos/chatbot/。生命週期如下：

1. 啟動 presenter。選擇 Avatar、Scene 和 Voice，點擊 Launch Presenter。Avatar 載入右側舞台——與 Basic Demo 完全相同。
2. 建立或選取 chatbot。點擊 + New Chatbot，輸入名稱和可選的系統指令，點擊 Save。Chatbot 透過 POST /api/chatbots 建立並立即選取。若要編輯或刪除現有 chatbot，從下拉選單中選取。
3. 聊天。輸入訊息並按送出。Avatar 進入 Thinking 狀態，等待 LLM 處理（POST /api/chatbots/:id/chat）。回覆顯示在聊天記錄中，並透過 presenter.present(reply_text) 大聲發話。若 presenter 尚未啟動，聊天仍以純文字模式運作。
4. 可選——Knowledge file 與 function tools。在 chatbot 編輯器中上傳 .txt、.pdf、 .doc、.docx 或 .csv 檔案，讓 chatbot 根據自有內容回答。建立或更新 chatbot 時傳入 tools 陣列，讓 chatbot 在對話中呼叫外部 HTTP API。

Chatbot

demos/chatbot/ デモは、Perxona Connect Chatbot API を同じ <sv-presenter> ステージと統合します。Presenter デモの上に、チャットボットの完全な CRUD、永続的なマルチターン会話、そして ナレッジファイルと function toolsを追加します。すべてのアシスタント応答は presenter.present() に渡され、アバターが各応答をリアルタイムで発話します。メッセージは Connect の parts 形式（{ role, parts: [{ type: 'text', text }] }）を使用し、上流のタイムアウトを避けるために 20 件のスライディングウィンドウで送信されます。 http://localhost:8083/demos/chatbot/ を開いてください。ライフサイクルは以下の通りです：

1. Presenter を起動。Avatar・Scene・Voice を選択して Launch Presenter をクリック。アバターが右側のステージに読み込まれます——Basic デモと同じ手順です。
2. チャットボットを作成または選択。 + New Chatbot をクリックし、名前と任意のシステム指示を入力して Save をクリック。チャットボットが POST /api/chatbots で作成され、即座に選択されます。既存のチャットボットを編集・削除するにはドロップダウンから選択してください。
3. チャット。メッセージを入力して送信。LLM が処理する間（POST /api/chatbots/:id/chat）アバターが Thinking 状態に入ります。返答がチャットログに表示され、presenter.present(reply_text) でアバターが音声で発話します。Presenter が未起動の場合はテキストのみで動作します。
4. オプション——ナレッジファイルとファンクションツール。チャットボットエディターで .txt・.pdf・.doc・.docx・.csv ファイルをアップロードして、独自コンテンツをもとに回答させることができます。チャットボット作成・更新時に tools 配列を渡すと、会話中に外部 HTTP API を呼び出せます。

API 參考

Express 伺服器公開以下路由。所有 /api/* 端點均回傳 JSON。伺服器使用其共享快取的 Bearer Token 將 catalog 讀取代理至 Connect API——不需要每個請求的瀏覽器驗證。

API リファレンス

Express サーバーは以下のルートを公開します。すべての /api/* エンドポイントは JSON を返します。サーバーは共有キャッシュの Bearer トークンを使って Connect API へカタログ読み取りをプロキシします——リクエストごとのブラウザ認証は不要です。

Presenter API

<sv-presenter> Web Component 從 Perxona 的 CDN 載入。在 DOM 中升級後透過其 JavaScript API 進行互動。

載入元件

從 GET /api/config → presenterUrl 取得 CDN URL 並動態注入——HTML 中不要硬編碼 URL：

Presenter API

<sv-presenter> Web コンポーネントは Perxona の CDN から読み込まれます。DOM でアップグレードされた後、JavaScript API を通じて操作します。

コンポーネントの読み込み

GET /api/config → presenterUrl から CDN URL を取得して動的に注入します——HTML に URL をハードコードしないでください：

完整初始化流程

完全な初期化フロー

API 成員

API メンバー

Motion Browser

Motion Browser 是一個獨立的開發者工具，讓你瀏覽 Perxona 完整的動作目錄、在 3D Avatar 上即時預覽每個動畫，並撰寫混合說話文字與動作指令的腳本——全在瀏覽器中完成。

核心概念：<sv-presenter> Web Component 支援行內動作標籤。在腳本文字中任意插入 [MOTION id:1]，Avatar 就會在說話的對應時間點執行該動作。

// Avatar 說 "I love" 的同時執行揮手動作，再繼續說話
await presenter.present("I love [MOTION wave:1] my avatar.");

示範

功能

• Avatar 預覽 — 全螢幕 3D 渲染，可從頂部選擇器即時切換角色。
• Motion Library — 瀏覽、搜尋、篩選所有可用動作。點擊任一卡片即可在 Avatar 上即時預覽。
• Script Composer — 富文字編輯器，可在說話文字中混入動作 chip；按下 Play，Avatar 按順序說話並執行動作。
• 場景與聲音切換 — 底部控制列可即時切換場景與聲音，無需重新載入。

快速開始

cd tools/motion-browser
cp .env.example .env   # 預設值已填入正式環境設定，無需修改
pnpm install
pnpm dev

以 pnpm dev 啟動後，開啟印出的 URL，以 Perxona 帳號登入並選擇 Avatar。 Presenter 會自動初始化並載入動作庫。

在腳本中插入動作標籤

1. 輸入說話文字

   在 Script Composer 中輸入 Avatar 要說的話。

2. 插入動作 chip

   在 Motion Library 面板找到目標動作。將游標放在文字中想要插入動作的位置，點擊 + 插入為 chip。

3. 按下 Play

   Avatar 說完整腳本，並在每個標記位置執行對應動作。chip 會序列化為 [MOTION <id>:1] 並直接傳入 presenter.present()。

Motion Browser

Motion Browser は、Perxona が提供するモーションカタログを探索し、3D アバター上でアニメーションをライブプレビューし、 テキストとモーション指定を組み合わせたスクリプトを作成できる、ブラウザベースの開発者ツールです。

中核となる考え方：<sv-presenter> Web コンポーネントはインラインモーションタグを理解します。 スクリプトテキストのどこにでも [MOTION id:1] を挿入すると、アバターはその発話のタイミングでモーションを実行します。

// "I love" と言う際にウェーブモーションを実行し、発話を続けます
await presenter.present("I love [MOTION wave:1] my avatar.");

デモ

機能

• アバタープレビュー — フルスクリーン 3D レンダリング。上部セレクターからキャラクターをリアルタイム切り替え。
• Motion Library — 利用可能なすべてのモーションを検索・フィルタリング。カードをクリックするとアバター上でライブプレビュー。
• Script Composer — テキストにモーションチップを混在させるリッチテキストエディター。Play を押すとアバターがシーケンス通りに発話＆モーション実行。
• シーン・音声切り替え — 下部コントロールバーでシーンと音声をリロードなしに即時変更。

開始する

cd tools/motion-browser
cp .env.example .env   # 本番設定が事前入力済み、編集不要
pnpm install
pnpm dev

pnpm dev 起動後、表示された URL を開いて Perxona アカウントでサインインし、 アバターを選択します。Presenter が自動初期化してモーションライブラリが読み込まれます。

スクリプトにモーションタグを挿入する

1. スピーチテキストを入力

   Script Composer にアバターに発話させたいテキストを入力します。

2. モーションチップを挿入

   Motion Library パネルで目的のモーションを見つけます。テキスト中の挿入したい位置にカーソルを置き、+ をクリックしてチップとして挿入します。

3. Play を押す

   アバターがスクリプト全体を発話し、各マーク位置でモーションを実行します。チップは [MOTION <id>:1] にシリアライズされ、presenter.present() に直接渡されます。

VRM Uploader

Perxona Connect Kit 可透過 Perxona 工作人員協助，將你自己的 VRM 1.0 角色加入 Avatar 目錄供選用——無需額外架設任何基礎設施。無論你想為產品打造品牌吉祥物、為受眾建立專屬的數位主持人，或是為個人專案製作原創角色，這都是從 .vrm 檔案到上線說話 Avatar 的最快路徑。

如需將 VRM 檔案上傳至你的帳戶，請洽詢 Perxona 工作人員，他們將協助完成所有上傳步驟，讓你的 Avatar 立即可以使用。

上傳完畢後，你便可以在 GET /assets/avatars 的 Avatar 清單中找到剛上傳的 VRM 角色，並將其應用在你的作品中。

VRM アップローダー

Perxona Connect Kit では、Perxona スタッフのアップロード支援を 受けて、自分の VRM 1.0 キャラクターをアバターカタログに追加できます——追加のインフラ構築は一切不要です。ブランドマスコット、独自のデジタルプレゼンター、個人プロジェクト向けのオリジナルキャラクターなど、どんな用途でも .vrm ファイルからライブで話すアバターへの最速ルートです。

VRM ファイルをアカウントにアップロードするには、Perxona スタッフにお声がけください。スタッフがアップロードをお引き受けし、すぐにご利用いただける状態にします。

アップロードが完了すると、GET /assets/avatars のアバターリストに新しい VRM キャラクターが表示され、すぐに作品に活用できます。

已知限制

• 範例，非生產環境。展示正常路徑——與完整 API 相比，未經強化、擴展或功能完整。
• 共享憑證模型。所有瀏覽器訪客共用同一個 Connect 身份（.env 的服務帳號）。適合 Demo；不適合生產環境的多租戶設計。
• CONNECT_TOKEN_EXPIRED 未連接。presenter 的 token 被拒絕時會觸發此事件。此範例未處理——長時間 session 時請重新載入頁面以獲取新 token。
• 聊天為可選功能。POST /api/chat 在 .env 中設定 LLM_API_KEY 之前回傳 501。
• 極簡 UI。刻意使用無框架的原生 JS——設計為可讀性優先，非生產就緒。

既知の制限

• サンプル、本番環境ではありません。ハッピーパスを示すもの——完全な API と比べて堅牢化・スケール・機能完備はされていません。
• 共有認証情報モデル。すべてのブラウザ訪問者が 1 つの Connect ID（.env のサービスアカウント）を共有します。デモには適していますが、本番のマルチテナント設計には不向きです。
• CONNECT_TOKEN_EXPIRED は未接続。Presenter のトークンが拒否された時にこのイベントが発行されます。このサンプルは処理しません——長時間セッションではページをリロードして新しいトークンを取得してください。
• チャットはオプション。POST /api/chat は .env に LLM_API_KEY が設定されるまで 501 を返します。
• 最小限の UI。意図的にフレームワークなしのバニラ JS——可読性を優先した設計で、本番向けではありません。

疑難排解

トラブルシューティング

後續步驟

基本 Demo 運行後，以下是自然的進一步方向：

• 使用你自己的 UI。用 React、Vue 或任何框架取代原生 JS 前端——伺服器 API（/api/*）保持不變。
• 處理 token 刷新。監聽 CONNECT_TOKEN_EXPIRED 事件並呼叫 presenter.refreshConnectToken(newToken) 以支援長時間 session。
• 啟用聊天。在 .env 中設定 LLM_API_KEY（及可選的 LLM_BASE_URL + LLM_MODEL）以解鎖 LLM 聊天面板。
• 探索完整 API 合約。參考 direct Connect API 的 OpenAPI spec samples/express/docs/openapi.yaml，並安裝 @perxona/presenter-types@latest 取得 presenter 型別宣告。
• 嘗試 Chatbot Demo。開啟 http://localhost:8083/demos/chatbot/ 建立並設定 chatbot，支援完整 CRUD、多輪對話記錄、knowledge file 上傳與可選的 function tools——全部整合至 avatar presenter。
• 追蹤更新並貢獻。Star 並 Watch 下方的 repository 以追蹤新功能和修復。

次のステップ

基本デモが動いたら、自然な次のステップを紹介します：

• 独自の UI を使用。バニラ JS フロントエンドを React、Vue、または任意のフレームワークで置き換えてください——サーバー API（/api/*）は変わりません。
• トークンリフレッシュの処理。長時間セッション向けに CONNECT_TOKEN_EXPIRED イベントを監視して presenter.refreshConnectToken(newToken) を呼び出してください。
• チャットを有効化。.env に LLM_API_KEY（オプションで LLM_BASE_URL + LLM_MODEL）を設定して LLM チャットパネルをアンロックしてください。
• 完全な API コントラクトを探索。direct Connect API の OpenAPI spec samples/express/docs/openapi.yaml を参照し、 presenter 型宣告には @perxona/presenter-types@latest をインストールしてください。
• チャットボットデモを試す。 http://localhost:8083/demos/chatbot/ を開いて、完全な CRUD・マルチターン会話履歴・ナレッジファイルアップロード・オプションのファンクションツールを備えたチャットボットを作成・設定してください——すべてアバター Presenter と連携しています。
• アップデートをフォロー・貢献。下のリポジトリをスターしてウォッチし、新機能とバグ修正を追跡してください。