GLB VRM 변환 API — 호출 세 번으로 .glb를 말하는 VRM 1.0으로

리깅 여부에 관계없이 휴머노이드 .glb를 업로드하고, 본이 매핑되고 말하고 깜박이는 얼굴이 있는 VRM 1.0을 다운로드하세요. Unity, Blender, 사람의 개입 없이 가능합니다.

API 키 받기 모델당 10 API 토큰 · .glb 최대 100MB, 리깅 여부 무관

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를 통해 표정소 및 깜박임 추가하기를 참조하세요.

API를 통해 첫 GLB 변환하기

키를 만들고 팩을 구매하세요. 모델당 10 API 토큰이 사용되며, 변환 실패 시 반환됩니다.

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 예제가 있습니다.

가이드