Live2D Cubism Editor 5.1 alpha3 External Application Integration Developer’s Manual |
04/25/2024 r3
Live2D Cubism Editor External API Integration
External Application Integration
List of External API Integration Functions
Version | Revision date | Revision details |
r3 | 04/25/2024 | Updated in alpha3 ・Added new APIs in “List of External API Integration Functions. ・GetPhysicsInfo, SetPhysicsInfo |
r2 | 04/11/2024 | Updated in alpha2 ・Modified parts of the table in "Data Format." ・Added information about connecting models with animation files to the "Instruction" section of the "List of External API Integration Functions." ・ClearParameterValues, SetGlobalVersion ・Deleted the animation part in Limitations as animation can now be integrated. |
r1 | 03/28/2024 | First edition |
Editors and external applications can be integrated through APIs.
Samples are available from Live2D Garage.
• GitHub Live2D GARAGE - CubismExternalAppPluginSamples
https://github.com/Live2D-Garage/CubismExternalAppPluginSamples
Telecommunications standard | WebSocket |
Format | JSON (UTF-8 text) |
Port | 22033 (Default port number) Can be changed arbitrarily. |
The Editor is the server and the external application is the client.
Token ?: String, |
Elements marked with “?” can be omitted from the specification.
{ "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. Optional †1. |
Timestamp | Number | Optional | Epoch milliseconds. 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 | |
Method | String | Required | |
Data | Any | Required | Additional data according to the operation. |
†1 This is a required element in version 0.9.0.
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. |
{ (Omitted) "Type": "Error", "Method": "SetParameterValues", "Data": { "ErrorType" : "InvalidParameter" } } |
Returns JSON with Type set to Error.
For Error Details, the type of error is entered in ErrorType.
See “Error type” for details.
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.
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.
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.
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.
{ "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.
Register an external application with Cubism Editor.
After registration is complete, a token is returned. This token is tied to the application and can be specified at the next connection to carry over the user’s permission status.
See “Token authentication” for details.
Version | Request | Response | ErrorType |
0.9.0 | Name:String, Token?:String, Icon?:String, Path?:String | Token:String | InvalidData |
Name:String | Application name (Optional) Give it a unique name. Even if another application uses the same name, the operation is not affected. |
Token?:String | Token If the specified token has already been registered, it is returned as is. |
Icon?:String | BASE64 string of icon PNG image Currently, it does not appear in the Editor even if specified. |
Path?:String | Application path information |
Precautions Almost all of the following instructions will return a PluginNotRegistered error and will not accept any operations through the API unless RegisterPlugin is completed first and permission is obtained from the user. |
Get whether the user has allowed communication with this app.
It is linked to the checkbox in the “Allow” column of the settings dialog box.
Version | Request | Response | ErrorType |
0.9.0 | Result:Boolean | InvalidData |
version 0.9
Obtains the model's current parameter ID and value by specifying the parameter ID.
Obtains all the model's parameter IDs and values if no parameter ID is specified.
Animation information is not included.
Version | Request | Response | ErrorType |
0.9.0 | ModelUID:string, Ids?:Array<string> | Parameters:Array<{ Id:String, Value:Number }> | InvalidData InvalidModel |
version 0.9.1
Obtains the model's current parameter ID and value by specifying the parameter ID.
Obtains all the model's parameter IDs and values if no parameter ID is specified.
Physics, model editing, and animation information can be received.
Version | Request | Response | ErrorType |
0.9.1 | ModelUID:string, Ids?:Array<string> | Parameters:Array<{ Id:String, Value:Number }> | InvalidData InvalidModel |
version 0.9.0
Sets the specified Parameter ID and value.
Parameters cannot be sent to the model in animation files.
Version | Request | Response | ErrorType |
0.9.0 | ModelUID:String, Parameters:Array<{ Id:String, Value:Number }> | InvalidData InvalidModel InvalidParameter |
version 0.9.1
Sets the specified parameter ID and value.
The model track must be selected to send parameters to the model in the animation file.
For models in the physics editor and animation mode, parameters are not immediately reflected but are temporarily stored.
Version | Request | Response | ErrorType |
0.9.1 | ModelUID:String, Parameters:Array<{ Id:String, Value:Number }> | InvalidData InvalidModel InvalidParameter |
Id:String | Parameter ID |
Name:String | Parameter name |
GroupUID:String | UID of the parameter group to which it belongs |
Default:Number | Default value |
Max,Max:Number | Maximum and minimum values |
Repeat:boolean | Repeat |
Type:Number | Parameter type 1: Blend Shape |
version 0.9.0
Obtains a list of the model’s parameters
Either ModelUID or DocumentUID can be omitted, but at least one is required.
Type '0' is for normal parameters, and '1' is for BlendShape parameters.
The list of the model’s parameters in the animation file (.can3) cannot be obtained.
Version | Request | Response | ErrorType |
0.9.0 | ModelUID?:String, DocumentUID?:String | Parameters:Array<{ Id:String, Name:String, GroupUID:String, Default:Number, Max:Number, Min:Number, Repeat:boolean Type:Number }> | InvalidData InvalidModel |
version 0.9.1
Obtains a list of the model’s parameters.
Either ModelUID or DocumentUID can be omitted, but at least one is required.
Type '0' is for normal parameters, and '1' is for BlendShape parameters.
The model track must be selected to obtain the parameter list of a model in the animation file.
In the case of a runtime model track, the GroupUID returns an empty string.
Version | Request | Response | ErrorType |
0.9.1 | ModelUID?:String, DocumentUID?:String | Parameters:Array<{ Id:String, Name:String, GroupUID:String, Default:Number, Max:Number, Min:Number, Repeat:boolean Type:Number }> | InvalidData InvalidModel |
version 0.9.0
Obtains a list of the model’s parameter groups.
Either ModelUID or DocumentUID can be omitted, but at least one is required.
The list of the model’s parameters in the animation file (.can3) cannot be retrieved.
Version | Request | Response | ErrorType |
0.9.0 | ModelUID?:String, DocumentUID?:String | Groups:Array<{ GroupUID:String, GroupName:String, }> | InvalidData InvalidModel |
version 0.9.1
Obtains a list of the model’s parameter groups.
Either ModelUID or DocumentUID can be omitted, but at least one is required.
The model track must be selected to obtain the group list of a model in the animation file.
In the case of a runtime model track, the GroupUID returns an empty string.
Version | Request | Response | ErrorType |
0.9.1 | ModelUID?:String, DocumentUID?:String | Groups:Array<{ GroupUID:String, GroupName:String, }> | InvalidData InvalidModel |
version 0.9.0
Returns document information.
It is separated by type, physics, and model editing, and returns an array of 0 documents if not present. Views will increase if a single model is displayed in a split view.
Version | Request | Response | ErrorType |
0.9.0 | PhysicsDocuments:Array<{ DocumentUID:String, DocumentFilePath:String, ModelUID:String }>, ModelingDocuments:Array<{ DocumentUID:String, DocumentFilePath:String, Views:Array<{ ModelUID:String }> }> | InvalidData InvalidDocument |
version 0.9.1
Returns the document information.
It is separated by type, physics, and model editing, and returns an array of 0 documents if no information is present. Views will increase if a single model is displayed in a split view.
Version | Request | Response | ErrorType |
0.9.1 | PhysicsDocuments : Array<{ DocumentUID : String, DocumentFilePath : String ModelUID : String, }> ModelingDocuments : Array<{ DocumentUID : String, DocumentFilePath : String Views : Array<{ ModelUID : String }> }> AnimationDocuments : Array<{ DocumentUID : String, DocumentFilePath : String Views : Array<{ ModelUID : String, ModelFilePath : String }> }> | InvalidData InvalidDocument |
version 0.9.0
Returns the UID of the current model in the Editor.
The UID of the model contained in the animation file cannot be retrieved.
Version | Request | Response | ErrorType |
0.9.0 | ModelUID:String | InvalidData InvalidModel |
version 0.9.1
Returns the UID of the current model in the Editor.
The model track must be selected to obtain the UID of a model in the animation file.
Version | Request | Response | ErrorType |
0.9.1 | ModelUID:String | InvalidData InvalidModel |
version 0.9.0
Returns the current edit mode in the Editor.
Version | Request | Response | ErrorType |
0.9.0 | EditMode:String | InvalidData |
EditMode:String | Edit mode Animation: Animation editing ModelingMeshEdit: Mesh editing |
version 0.9.1
Sets the API version to use.
This allows you to fix the API version for external applications. If it is not set, you can reset it to unspecified.
Version | Request | Response | ErrorType |
0.9.1 | Version ?: String | InvalidData |
version 0.9.1
Clears the parameters sent to the target model.
Parameters sent with SetParameterValue are temporarily stored in Cubism Editor.
Parameters may be temporarily stored in the physics editor and animation view due to model updates. Use this API if you want to explicitly clear the temporary parameters.
Version | Request | Response | ErrorType |
0.9.1 | ModelUID : String | InvalidData |
version 0.9.2
Obtains Calculate FPS from Cubism Editor’s physics settings.
Version | Request | Response | ErrorType |
0.9.2 | ModelUID : String | Fps : Number | InvalidData InvalidModel |
version 0.9.2
Obtains Calculate FPS from Cubism Editor's physics settings.
Cubism Editor determines the valid FPS input range (10-120).
Omitting the FPS will reset the Calculate FPS setting in Cubism Editor.
Version | Request | Response | ErrorType |
0.9.2 | ModelUID : String, Fps ?: Number | InvalidData InvalidModel |
When handling events, the client must first enable the permission flag for the server.
{ (Omitted) "Type": "Request", "Method": "NotifyMocFileExported", "Data": { "Enable" : true } } |
Then, when the server performs a specific process (event), it sends JSON data without requiring a request from the client.
{ (Omitted) "Type": "Response", "Method": "NotifyMocFileExported", "Data": { "Path" : "c:\\temp\\export.moc3", "ModelFilePath" : "c:\\models\\hoge03.cmo3" } } |
Sets the notification settings for exporting physics settings files.
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
Sets the notification settings for exporting MOC3 files.
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
Sets the notification settings for exporting motion files.
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
Sets the notification settings for exporting motion-sync settings files.
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | Path:String, ModelFilePath:String | InvalidData |
Sets the notification settings for when the Edit mode is switched.
For more information about EditMode, see “GetCurrentEditMode.”
Version | Request | Response | Event | ErrorType |
0.9.0 | Enabled:Boolean | Accepted:Boolean | EditMode:String | InvalidData |
Name | Description | Since |
InvalidJson | The JSON structure is incorrect. | 0.9.0 |
UnsupportedVersion | Incompatible versions. | 0.9.0 |
MethodNotFound | The specified instruction cannot be found. | 0.9.0 |
InvalidType | The Type setting is incorrect. | 0.9.0 |
InvalidData | One or more instruction arguments are incorrect. | 0.9.0 |
PluginNotRegistered | Plug-in registration is not complete. | 0.9.0 |
InvalidParameter | The specified Live2D parameter does not exist. | 0.9.0 |
InvalidModel | The specified Live2D model does not exist. | 0.9.0 |
InvalidDocument | The specified document does not exist in the Editor. | 0.9.0 |
InvalidView | The specified View does not exist. | 0.9.0 |
This alpha version includes some unimplemented features, known defects, and other items of concern that should be specifically noted. Normally, these limitations will be dealt with when upgrading from the alpha version, but this is not guaranteed.
Model information contained in animation files cannot be retrieved.
Note: Fixed in 5.1 alpha2
When integrating with an external application, even if Icon is set in a call to RegisterPlugin in the API, it is not reflected in the UI of the External Application Integration Settings dialog box.
Note: It is planned to be supported in 5.1 beta1 and later.
