Live2D Cubism 编辑器外部链接 API

最終更新： 2024年6月25日

编辑器和外部应用程序可以通过API进行协作。

外部应用示例

Live2D Garage 的示例发布在 GitHub 上。

通讯方式

编辑器是服务器，外部应用程序是客户端。

通讯标准	WebSocket
格式	JSON（UTF-8 文本）
港口	22033 *默认端口号 可以任意更改。

缩写

标有“？”的元素可以省略。

Token ?: String,

数据形式

{
    "Version": "1.0.0",
    "Timestamp": 1696233943287,
    "RequestId": "13",
    "Type": "Request",
    "Method": "GetCurrentModelUID",
    "Data": {}
}

发送和接收均采用以下 JSON 格式进行。
版本到类型对于所有指令都是通用的。

元素	类型	要求	解释
Version	String	任何	指定 API 和指令的版本。 您可以修复要交换的版本并保持兼容性。 如果设置不受支持的版本，则会出现错误。选修的。 (*1)
Timestamp	Number	任何	纪元毫秒，可选。
RequestId	String	任何	返回服务器响应时发送的 ID。 如果省略，它也会在服务器响应中被省略。
Type	String	必需的	API调用
Method	String	必需的	说明
Data	Any	必需的	根据操作添加数据。 Data{} 的内容（相当于参数）根据说明而有所不同。

(*1) 这是 0.9.0 版本中的必需元素。

API调用

类型	解释
Request	要求： 主要是在从客户端（外部应用程序）向服务器（编辑器）发送命令时设置。
Response	回复： 主要是在服务器响应客户端指令时设置。
Event	事件： 主要是在任意时刻（没有客户端请求时）服务器自发响应客户端时设置的。
Error	错误： 如果Request无效，则将设置了该值的API返回给客户端。

错误处理

返回错误类型的 JSON。错误类型在 ErrorType 中输入。
有关详细信息，请参阅“错误类型”。

{
    (省略)
    "Type": "Error",
    "Method": "SetParameterValues",
    "Data": {
        "ErrorType" : "InvalidParameter"
    }
}

令牌认证

为了保护编辑器免受意外外部应用程序的影响，它有一个内置的身份验证系统，该系统会阻止来自外部应用程序的通信，除非用户授予许可。

第一次连接

连接后，首先使用RegisterPlugin获取新的令牌。

即使获得了代币，也不意味着可以自由交流。
仅当用户从设置对话框中启用“允许”复选框时才能使用 API。
因此，外部应用程序将不得不等到那时。

从第二次开始连接

从第二次开始，您可以跳过用户权限。
请在RegisterPlugin中指定先前连接中使用的令牌。
如果用户允许，RegisterPlugin 将按原样返回指定的令牌，并使 API 立即可用。

如果令牌未经授权，则通信将被阻止，直到用户通过返回新令牌再次授权为止。

加工流程

参数反射时序

API基本上是立即执行的，但是由于物理计算和随机姿势，参数的反映时间存在延迟。
实际上，它是通过临时缓冲区反映的，如下所示。

临时缓冲液保留期限

临时缓冲区使用超过0.5秒后会自动销毁。
此机制可防止您锁定编辑器中的操作。
请注意，例如，在以下情况下，无法获取预期参数。

UID和参数ID

{
    "Data": {
        "ModelUID" : "8456858123561231456" // UID
    }
}

{
    "Data": {
        "Parameters" : [{"Id":"ParamAngleY","Value":"0.0"}] // ParameterID
    }
}

参数 ID 是一个不可变的值（除非您对模型进行更改），而 UID 是一个临时 ID，其值可以根据连接的不同而更改。

通过外部链接 API 从这些 UID 和参数 ID 在编辑器中设置和检索信息。
更多信息请参见“外部联动API列表”。