Live2D Cubism Editor External API Integration
Updated: 06/25/2024
Editors and external applications be integrated through APIs.
External application samples
Samples are available on GitHub in Live2D Garage.
Communication system
The Editor is the server and the external application is the client.
| Telecommunications standard | WebSocket |
| Format | JSON (UTF-8 text) |
| Port | 22033 Note: Default port number The number can be changed as desired. |
Abbreviated notation
Elements marked with “?” can be omitted from the specification.
Token ?: String,
Data format
{
"Version": "1.0.0",
"Timestamp": 1696233943287,
"RequestId": "13",
"Type": "Request",
"Method": "GetCurrentModelUID",
"Data": {}
}
Sending and receiving both use the following JSON format.
Elements, from Version to Type, are common to all instructions.
| Element | Type | Requirement | Description |
|---|---|---|---|
| Version | String | Optional | Specifies the API and instruction version. This allows the versions used for the exchange to be fixed to maintain compatibility. If noncorresponding versions are set, an error will occur. This element can be omitted. (*1) |
| Timestamp | Number | Optional | Epoch milliseconds, which can be omitted. |
| RequestId | String | Optional | Returns the ID sent in the transmission upon response from the server. If omitted, it is also omitted in the server response. |
| Type | String | Required | API type |
| Method | String | Required | Instruction |
| Data | Any | Required | Additional data according to the operation. The contents of Data{} (equivalent to the argument) depend on instruction. |
(*1) This element is required in version 0.9.0.
API type
| Type | Description |
|---|---|
| Request | Request: This is mainly set when sending instructions from the client (external application) to the server (Editor). |
| Response | Response: This is primarily set when the server responds to instructions from the client. |
| Event | Event: This setting is mainly used when the server spontaneously responds to the client at an arbitrary time (when there is no request from the client). |
| Error | Error: If the Request is invalid, an API response with this value is returned to the client. |
Error handling
Returns JSON with Type set to Error. For Error Details, the type of error is entered in ErrorType.
See “Error type” for details.
{
(Omitted)
"Type": "Error",
"Method": "SetParameterValues",
"Data": {
"ErrorType" : "InvalidParameter"
}
}
Token authentication
To protect the Editor from unintended external apps, an authentication system is built in that blocks communication from external apps unless the user gives permission.
Initial connection
After connecting, the first step is to obtain a new token with RegisterPlugin.
Obtaining a token does not mean that you can communicate freely.
The API is available only when the user enables the “Allow” checkbox from the settings dialog box.
Therefore, external applications must wait until this has been completed.
Second and subsequent connections
Permission by the user can be skipped from the second time.
Specify the token used in the previous connection in RegisterPlugin.
If the user allows it, RegisterPlugin returns the specified token as is, and the API is ready to use immediately.
If the token is not allowed, a new token is returned and communication is blocked until the user allows it again.
Process flow
Parameter reflection timing
The API is based on immediate execution, but parameters have a delay in reflection timing due to physics operations and random poses.
This is reflected via a temporary buffer as follows.
Temporary buffer retention period
The temporary buffer is automatically discarded after 0.5 seconds of use.
This mechanism prevents the Editor from locking up the operation.
As a precaution, the intended parameters cannot be obtained in the following example case.
UID and parameter ID
{
"Data": {
"ModelUID" : "8456858123561231456" // UID
}
}
{
"Data": {
"Parameters" : [{"Id":"ParamAngleY","Value":"0.0"}] // ParameterID
}
}
Parameter ID is a nonchanging value (unless changes are made to the model), while the UID is a temporary ID whose value may change with each connection.
Information in the Editor is set and retrieved from these UIDs and parameter IDs through the external API integration functions.
For details, see “List of external API integration functions.”