Live2D Cubism Editor External API Integration

Updated: 10/24/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"
    }
}

Rules

For all instructions, if possible, wait for the completion of the instruction (response) before executing the next instruction.

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.”