Live2D Cubism Editor 外部連携 API
最終更新： 2024年10月24日
エディタと外部アプリケーションでAPIを通して連携することができます。
外部アプリケーションのサンプル
Live2D GarageにサンプルをGitHubで公開しています。
通信方式
エディタがサーバー、外部アプリケーションがクライアントになります。
| 通信規格 | 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 | 任意 | エポックミリ秒、省略可能です。 |
| RequestId | String | 任意 | サーバーからのレスポンス時に送信で送ったIDを返します。 省略した場合、サーバーレスポンスでも省略されます。 |
| Type | String | 必須 | APIタイプ |
| Method | String | 必須 | 命令 |
| Data | Any | 必須 | 操作に応じた追加データです。 Data{}（引数に相当）の中身は命令により異なります。 |
（※1）バージョン0.9.0では必須の要素です。
APIタイプ
| タイプ | 説明 |
|---|---|
| Request | 要求： 主にクライアント（外部アプリケーション）からサーバー（エディタ）に命令を送る際に設定されます。 |
| Response | 応答： 主にサーバーがクライアントからの命令に答える際に設定されます。 |
| Event | イベント： 主にサーバーが任意のタイミング（クライアントからRequestが無い状態）で、自発的にクライアントへ応答する際に設定されます。 |
| Error | エラー： Requestに不正があった場合、この値が設定されたAPIをクライアントへ返します。 |
エラーハンドリング
TypeがErrorのJSONを返します。エラー内容はErrorTypeに種類が記入されます。
詳細は「 エラータイプ」をご覧ください。
{
(省略)
"Type": "Error",
"Method": "SetParameterValues",
"Data": {
"ErrorType" : "InvalidParameter"
}
}
規則
すべての命令において、可能な限り命令の完了（レスポンス）を待ってから次の命令を実行してください。
トークン認証
意図しない外部アプリからエディタを守るため、ユーザーが許可しない限り外部アプリからの通信を遮断する認証システムが組み込まれています。
初回接続
接続後にまず最初にRegisterPluginで新規トークンを取得します。
トークンを取得しても自由に通信が行えるわけではありません。
ユーザーが設定ダイアログから「許可」のチェックボックスを有効にすることで、初めてAPIが使用可能となります。
よって、外部アプリはそれまで待機する必要があります。
2回目からの接続
2回目からはユーザーによる許可をスキップすることができます。
先の接続で使用したトークンをRegisterPluginで指定してください。
ユーザーが許可した場合、RegisterPluginは指定したトークンをそのまま返して即APIが使える状態にします。
トークンが許可されていない場合は、新しいトークンを返してユーザーがもう一度許可するまで通信は遮断されます。
処理の流れ
パラメータの反映タイミング
APIは即時実行が基本ですが、パラメータは物理演算やランダムポーズの関係で反映タイミングに遅延があります。
実際は以下のように一時バッファを経由して反映されます。
一時バッファの保持期間
一時バッファは使用後0.5秒間を超えると自動で破棄されます。
この機構はエディタにおいて操作をロックしてしまうことを防ぎます。
注意として、例えば以下のケースでは意図したパラメータが取得できません。
UIDとパラメータID
{
"Data": {
"ModelUID" : "8456858123561231456" // UID
}
}
{
"Data": {
"Parameters" : [{"Id":"ParamAngleY","Value":"0.0"}] // ParameterID
}
}
パラメータIDは（モデルに変更を加えない限り）不変な値ですが、UIDは接続ごとに値が変化する可能性がある一時的なIDです。
これらのUIDやパラメータIDなどから外部連携APIを通してエディタ内の情報を設定および取得します。
詳しくは「外部連携API一覧」をご覧ください。