GLB VRM 변환 API — 호출 세 번으로 .glb를 말하는 VRM 1.0으로
리깅 여부에 관계없이 휴머노이드 .glb를 업로드하고, 본이 매핑되고 말하고 깜박이는 얼굴이 있는 VRM 1.0을 다운로드하세요. Unity, Blender, 사람의 개입 없이 가능합니다.
GLB를 VRM으로 프로그래밍 방식으로 변환하려면, API 키를 사용하여 .glb(최대 100MB)를 https://app.riggle3d.com/api/v1/conversions로 POST하고, 3-5초마다 GET /conversions/{id}를 폴링한 후, status가 succeeded가 되면 GET /conversions/{id}/vrm을 다운로드합니다. 결과물은 휴머노이드 본, 5가지 표정소, 깜박임, 3가지 감정, 그리고 리그에 눈 뼈가 있는 경우 lookAt 기능이 포함된 VRM 1.0입니다. GLB에 스켈레톤이나 얼굴 셰이프가 없어도 1-3분 내에 자동으로 빌드됩니다. 비용은 10 API 토큰($1.00 ~ $1.50, 팩에 따라 다름)이며, 변환 실패 시 토큰은 반환됩니다.
세 번의 호출
export RIGGLE_API_KEY=rgl_...
API=https://app.riggle3d.com/api/v1
# 1. 변환 시작 (10 API 토큰)
id=$(curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F file=@character.glb | jq -r .id)
# 2. 더 이상 처리 중이 아닐 때까지 폴링
until [ "$(curl -s $API/conversions/$id \
-H "Authorization: Bearer $RIGGLE_API_KEY" | jq -r .status)" != processing ]
do sleep 4; done
# 3. VRM 다운로드
curl -s -o character.vrm $API/conversions/$id/vrm \
-H "Authorization: Bearer $RIGGLE_API_KEY"이것이 전체 통합 과정입니다: 생성, 폴링, 다운로드. 필드, 변환 객체 및 모든 오류는 API 레퍼런스에 있으며, 종속성 없는 Python 및 Node 클라이언트는 github.com/riggle3d/glb-to-vrm에 있습니다.
폴링하는 동안, stage는 변환이 어느 단계에 있는지 알려줍니다: rigging(GLB에 스켈레톤이 없는 경우에만), marking_face, 그 다음 building_vrm.
직접 구축하기 어려운 이유
VRM은 확장 기능이 있는 glTF이므로 컨테이너를 작성하는 것은 쉬운 부분입니다. 시간이 걸리는 것은 확장 기능이 설명하는 모든 것입니다:
- 휴머노이드 본. VRM은 어느 관절이
hips이고 어느 것이leftUpperArm인지 알아야 하며, 모든 소스는 각기 다른 방식으로 본의 이름을 지정하고 배열합니다: Mixamo, Tripo, VRoid, Character Creator, 게임 리그, 전혀 사용할 수 없는 이름의 리그 등. - VRM 1.0 표정. 파일에는
aa,blink,happy등이 필요합니다. AI 생성기나 자동 리거에서 나온 GLB는 거의 얼굴 셰이프가 하나도 없으므로 이름을 붙일 것이 없습니다. - 표정소를 위해서는 입이 열려야 합니다. 입을 다물고 만든 모델은 입구가 전혀 없으며, 아래턱 전체를 움직이면 부자연스러워 보입니다.
- 확인. 파일에 표정이 존재하더라도 화면에서는 아무것도 움직이지 않을 수 있습니다.
대신 API는 완성된 파일을 제공합니다: 본이 제자리에 있고, 말하고, 깜박이고, 감정을 표현하는 얼굴이 있는 VRM 1.0과 이를 확인할 수 있는 미리보기 비디오를 제공합니다. GLB에 스켈레톤이나 얼굴 셰이프가 있었는지 여부와는 관계없습니다.
전송하는 것과 받는 것
입력: 휴머노이드 캐릭터의 .glb 파일 하나, 최대 100MB, multipart 필드 file로 전송. 리깅 또는 미리깅. 선택적 name, 그리고 재시도된 요청이 두 번 청구되지 않도록 하는 선택적 Idempotency-Key 헤더.
출력: 휴머노이드 본, 표정소 aa ih ee oh ou, blink, blinkLeft, blinkRight, happy, angry, surprised, 그리고 리그에 눈 뼈가 있는 경우 lookAt이 포함된 VRM 1.0; 모든 표정을 재생하는 preview.mp4; preview_images에 나열된 스틸 이미지; 그리고 warnings.
warnings를 읽어보세요. 빈 목록은 이상이 없음을 의미합니다. 경고는 아바타가 빌드되었지만 미리보기를 확인해야 함을 의미합니다: 얼굴이 낮은 신뢰도로 감지되었거나 표정소가 거의 움직이지 않을 수 있습니다. 입의 품질은 모델에 따라 다릅니다. 입을 벌리고 모델링된 캐릭터는 가장 자연스러운 입 모양을 제공하며, 닫힌 입은 더 부드러운 움직임을 보입니다.
가격
| 팩 | API 토큰 | 가격 | 변환된 GLB당 비용 |
|---|---|---|---|
| 스타터 | 100 | $15 | $1.50 |
| 빌더 | 500 | $60 | $1.20 |
| 스케일 | 2,500 | $250 | $1.00 |
하나의 GLB to VRM 변환은 10 API 토큰입니다. 폴링, VRM 다운로드, 미리보기 및 삭제는 무료입니다. 토큰은 만료되지 않으며 실패한 변환은 자동으로 토큰을 반환합니다. 무료 API 토큰은 없습니다. 팩을 구매해야 키가 작동합니다.
누구를 위한 것인가
- AI 아바타 및 동반자 앱. 사용자가 캐릭터를 가져오거나 생성하면, 앱은 TTS에 맞춰 립싱크를 해야 합니다. GLB를 보내고, VRM을 저장하고, 오디오에서
aa ih ee oh ou를 구동하세요. - VTuber 도구. 가져올 때 모든 휴머노이드 GLB를 수락하고 사용자에게 이미 깜박이고 말하는 아바타를 제공하세요.
- 게임 및 캐릭터 파이프라인. 캐릭터 라이브러리를 VRM 1.0으로 일괄 변환하세요. 계정당 한 번에 최대 세 개까지 가능합니다.
- 3D 생성기. 이미 GLB를 생성하고 있습니다. 단 한 번의 요청으로 옆에 "VRM으로 내보내기" 버튼을 추가할 수 있습니다.
수동으로 하나의 모델을 변환하시나요? GLB to VRM 변환기는 브라우저에서 동일한 작업을 수행합니다. 모델이 아닌 사진에서 시작하시나요? 이미지를 VRM으로 변환하는 API를 참조하세요. 얼굴이 움직이지 않는 VRM이 이미 있으신가요? API를 통해 표정소 및 깜박임 추가하기를 참조하세요.
크리에이터들이 자주 묻는 질문
GLB를 리깅해야 하나요?
아니요. 스켈레톤이 없는 GLB도 작동합니다. Riggle이 스켈레톤을 추가하며, 이 과정 동안 stage는 rigging으로 표시됩니다. 가격은 동일하게 10 API 토큰입니다.
제 GLB에는 블렌드셰이프가 없습니다. VRM이 여전히 말할 수 있나요?
네, API는 바로 그런 경우를 위해 만들어졌습니다. VRM은 표정소, 깜박임, 감정 표현과 함께 반환되므로 GLB 자체에 얼굴 셰이프가 필요 없습니다.
변환하는 데 시간이 얼마나 걸리나요?
리깅된 모델의 경우 1~3분입니다. 3~5초마다 GET /conversions/{id}를 폴링하세요. 웹훅은 없습니다.
모델당 비용은 얼마인가요?
10 API 토큰입니다: 스타터 팩($15에 100 토큰)은 $1.50, 빌더 팩($60에 500 토큰)은 $1.20, 스케일 팩($250에 2,500 토큰)은 $1.00입니다. 변환 실패 시 토큰은 반환됩니다.
.gltf, FBX 또는 URL을 보낼 수 있나요?
아니요. API는 요청 시 업로드된 단일 .glb 또는 .vrm 파일만 받습니다. .gltf는 .bin 및 텍스처와 함께 하나의 .glb로 묶고, FBX는 .glb로 내보낸 후 보내주세요.
VRM 0.x를 출력하나요?
아니요, VRM 1.0만 출력합니다.
변환이 실패하면 어떻게 되나요?
변환 상태는 error.code가 conversion_failed이고 메시지가 포함된 failed 상태가 되며, 10개의 토큰은 자동으로 반환됩니다(refunded는 true가 됨).
많은 GLB를 한 번에 변환할 수 있나요?
계정당 최대 3개의 변환을 진행할 수 있습니다. 나머지는 귀사 측에서 대기열에 넣고 하나가 끝나면 다음 변환을 시작하세요. 네 번째 요청은 429 too_many_active를 받게 됩니다.
클라이언트 라이브러리가 있나요?
패키지 형태로는 없습니다. github.com/riggle3d/glb-to-vrm에는 프로젝트에 복사하여 사용할 수 있는 종속성 없는 Python 클라이언트와 종속성 없는 Node 클라이언트, 그리고 curl 예제가 있습니다.