Live2D Cubism Editor 외부 연계 API

업데이트： 2024/06/25

편집기와 외부 애플리케이션에서 API를 통해 연동할 수 있습니다.

외부 애플리케이션 샘플

Live2D Garage에 GitHub에서 샘플을 게시하고 있습니다.

통신 방식

편집기가 서버이고 외부 응용 프로그램이 클라이언트가 됩니다.

통신 표준	WebSocket
형식	JSON(UTF-8 텍스트)
포트	22033 ※기본 포트 번호 <br/>임의로 변경 가능합니다.

생략 표기

「?」가 붙어 있는 요소는, 지정을 생략하는 것이 가능합니다.

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를 사용할 수 있습니다. 따라서 외부 앱은 그때까지 기다려야 합니다.

두 번째부터 연결

두 번째부터는 사용자의 권한을 건너뛸 수 있습니다. 이전 연결에서 사용한 토큰을 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 목록‘을 참조하세요.