Live2D Cubism Editor 外部集成 API

最終更新： 2024年10月24日

Editor和外部应用程序可以通过API进行集成。

外部应用程序范例

Live2D Garage的范例已发布在GitHub上。

通信方式

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

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

缩写

带有“?”标记的元素可以省略指定。

Token ?: String,

数据形式

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

发送和接收均采用以下JSON格式进行。
Version~Type对于所有命令都是通用的。

元素	类型	要求	说明
Version	String	任意	指定API、命令的版本。 您可以固定要交换的版本并保持兼容性。 如果设置未支持的版本，则会出现错误。可省略。（*1）
Timestamp	Number	任意	Epoch毫秒，可省略。
RequestId	String	任意	返回服务器响应时发送的ID。 如果省略，则在服务器响应中也会被省略。
Type	String	必须项	API类型
Method	String	必须项	命令
Data	Any	必须项	根据操作追加的数据。 Data{}（相当于参数）的内容因命令而异。

（*1）这是0.9.0版本中的必需元素。

API类型

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

错误处理

Type返回Error的JSON。在ErrorType中填写错误内容的类型。
有关详细信息，请参考“错误类型”。

{
    （省略）
    "Type": "Error",
    "Method": "SetParameterValues",
    "Data": {
        "ErrorType" : "InvalidParameter"
    }
}

规则

对于所有命令，请尽可能等待命令完成（响应），然后再执行下一个命令。

令牌认证

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

首次连接

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

即使获得了令牌，也不意味着可以自由通信。
仅当用户从设置对话框中启用“权限”复选框时才能使用API。
因此，外部应用程序将不得不等到那时。

第二次起的连接

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

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

处理流程

参数的应用时机

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

临时缓冲区保留期限

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

UID和参数ID

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

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

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

通过外部集成API从这些UID和参数ID在Editor中设置和获取信息。
有关详细信息，请参考“外部集成API列表”。