Live2D Cubism Editor 外部連携 API

最終更新： 2024年6月25日

エディタと外部アプリケーションで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一覧」をご覧ください。