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 standardWebSocket
FormatJSON (UTF-8 text)
Port22033 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.

ElementTypeRequirementDescription
VersionStringOptionalSpecifies 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)
TimestampNumberOptionalEpoch milliseconds, which can be omitted.
RequestIdStringOptionalReturns the ID sent in the transmission upon response from the server.
If omitted, it is also omitted in the server response.
TypeStringRequiredAPI type
MethodStringRequiredInstruction
DataAnyRequiredAdditional 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

TypeDescription
RequestRequest:
This is mainly set when sending instructions from the client (external application) to the server (Editor).
ResponseResponse: 
This is primarily set when the server responds to instructions from the client.
EventEvent: 
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).
ErrorError:
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 commands, please wait for their completion (response) whenever possible before executing the next command.

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

Was this article helpful?
YesNo
Please let us know what you think about this article.