ExAPI - 用 WebSocket 控制 Live2DViewerEX

ExAPI 是什么

ExAPI 是 Live2DViewerEX 提供的一组 WebSocket API，让开发者可以通过网络协议远程控制 Live2DViewerEX 的各个模块。

简单说就是：你写的任何软件（Python 脚本、Node.js 应用、浏览器扩展、移动端 App）都可以通过 ExAPI：

• 切换当前显示的模型
• 替换桌面背景
• 发送气泡消息让角色说话
• 控制特效和滤镜开关
• 切换场景快照
• 获取当前状态

连接方式

WebSocket 地址

ws://127.0.0.1

Live2DViewerEX 默认监听本机的 WebSocket，不对外暴露。这意味着：

• 只有本机上运行的软件能连接（安全设计）
• 如果你想从另一台电脑连接，需要自己做端口转发

启动前准备

控制面板 → 设定 → 开发者相关 → 开启 ExAPI。

不开启的话 WebSocket 不会监听。

连接后协议

WebSocket 消息使用 JSON 格式。请求和响应都有统一的结构。

支持的操作（总览）

典型用例

用例 1：语音助手触发气泡

你可以把 Live2DViewerEX 接到自己的自动化脚本里，让模型"说话"：

• 早上闹钟响时 → 自动切换场景到"早晨问候" → 发送气泡"早上好！"
• 语音助手（如 Siri Shortcut）触发 → Live2D 模型跟着语音同步说话
• 定时提醒 → 模型跳出来"该喝水了"

用例 2：游戏联动

• 打开某款游戏时 → Live2DViewerEX 自动加载和游戏同题材的模型和背景
• 游戏结束切回桌面时 → 恢复到日常场景
• 可以和游戏内事件联动（如升级时模型弹出庆祝气泡）

用例 3：多场景自动切换

• 写一个 Python 脚本，根据时间自动切换场景：
• 早上 8:00 → 晨光场景（暖色滤镜 + 模拟时钟 + 日程提醒气泡）
• 下午 3:00 → 工作场景（简洁背景 + 资源监视器）
• 晚上 10:00 → 夜景场景（深色滤镜 + 雪花特效）

用例 4：网页端远程控制

写一个本地网页（通过 ExAPI）：

• 界面上是一排模型预览图，点一下就切换
• 背景图列表，点一下就换
• 特效开关，实时反馈
• 相当于一个手机端遥控 Live2DViewerEX 的面板

请求和响应格式

请求消息

{
  "action": "model.load",
  "data": {
    "slot": 0,
    "modelName": "my_favorite_model"
  }
}

响应消息

{
  "success": true,
  "action": "model.load",
  "data": {
    "slot": 0,
    "modelName": "my_favorite_model"
  }
}

实际支持哪些 action 名称、data 字段长什么样，需要查官方文档。Live2DViewerEX 在不断更新 ExAPI，以官方最新版为准。

开发注意事项

ExAPI 仅 Windows / macOS / Android

iOS Motion Tracker 只是面捕工具，没有 ExAPI。

127.0.0.1 不能被 VPN 干扰

Live2DViewerEX 的控制面板和渲染器之间也用 WebSocket 通信（同样监听 127.0.0.1）。如果你开了 VPN 把本地流量也接管了，可能会导致应用本身"连接失败"——详见下一节常见问题。

防火墙设置

确保防火墙没有阻断 Live2DViewerEX 的本地通信。控制面板 → 设定里可以找到 WebSocket 端口配置。

快速入门示例（Python）

下面是一个用 Python 通过 ExAPI 发送气泡的极简示例：

import asyncio
import websockets
import json

async def send_bubble():
    async with websockets.connect("ws://127.0.0.1") as ws:
        msg = {
            "action": "bubble.send",
            "data": {
                "text": "你好，我是自动消息！"
            }
        }
        await ws.send(json.dumps(msg))
        response = await ws.recv()
        print(response)

asyncio.run(send_bubble())

需要安装 websockets 库（pip install websockets）。

这个示例需要 Live2DViewerEX 已启动并且 ExAPI 已开启。

官方文档

详细的 ExAPI 文档在官方文档站：live2d.pavostudio.com/doc/zh-cn/exapi/。