Riggle VRM API — 레퍼런스
단일 REST API로 리깅 여부와 관계없이 3D 캐릭터 또는 캐릭터 사진을 가져와 말하고 깜박이는 VRM 1.0을 반환합니다. 이 페이지는 인증, 가격, 모든 엔드포인트, 변환 객체 및 오류에 대한 전체 레퍼런스입니다.
Riggle VRM API는 .glb 또는 .vrm 파일(리깅/미리깅, 최대 100MB) 또는 단일 캐릭터의 .png/.jpg 파일을 휴머노이드 본, 5가지 표정소(aa, ih, ee, oh, ou), blink, blinkLeft, blinkRight, happy, angry, surprised 및 리그에 눈 뼈가 있는 경우 lookAt 기능이 포함된 VRM 1.0으로 변환합니다. POST /conversions, 3-5초마다 GET /conversions/{id} 폴링, 그리고 GET /conversions/{id}/vrm의 세 번의 호출로 이루어집니다. 모델은 10 API 토큰($1.00 ~ $1.50), 사진은 25 API 토큰이 비용으로 청구되며, 변환 실패 시 토큰은 자동으로 반환됩니다.
빠른 시작
app.riggle3d.com/developers에서 키를 만드세요. API 토큰 팩을 구매해야 키가 작동하며, 무료 토큰은 없습니다. 그런 다음:
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"리깅된 모델은 1-3분, 사진은 3-6분이 소요됩니다. 종속성 없는 Python 및 Node 클라이언트와 동일한 흐름 및 더 많은 curl 예제는 github.com/riggle3d/glb-to-vrm에서 확인할 수 있습니다.
기본 및 인증
- 기본 URL:
https://app.riggle3d.com/api/v1 - 인증:
Authorization: Bearer rgl_…모든 요청에 적용됩니다. 키는 개발자 페이지에서 생성 및 폐기할 수 있으며, 비밀 키는 한 번만 표시되므로 생성 시 저장해야 합니다. - 요청은
multipart/form-data(업로드)이거나 본문이 없습니다. 응답은 파일 다운로드를 제외하고 JSON 형식입니다. - 모든 것이 비동기식입니다. 변환을 생성하고,
status가succeeded또는failed가 될 때까지 3-5초마다 폴링한 다음 다운로드합니다. - 자동화. 사람의 개입이 필요한 단계는 없습니다. 리깅된 모델, 미리깅된 모델, 사진 모두 동일한 세 번의 호출을 통해 처리됩니다.
API 토큰 및 가격
API는 자체 잔액인 API 토큰으로 결제됩니다. 개발자 페이지에서 구매할 수 있으며 만료되지 않습니다. 웹 앱의 Studio 토큰과는 다릅니다. 어느 종류의 토큰으로도 다른 쪽의 작업을 결제할 수 없으며, 서로 교환할 수도 없습니다.
| 작업 | API 토큰 |
|---|---|
모델(.glb / .vrm, 리깅 여부 무관) → VRM | 10 |
사진(.png / .jpg) → 3D 모델 → VRM | 25 |
...사진을 먼저 다시 그리는 경우(fix=true, 필요한 경우에만) | +2 |
사진만 다시 그리기(POST /pictures/fix) | 2 |
| 상태, 목록, 다운로드, 미리보기, 삭제 | 0 |
| 팩 | API 토큰 | 가격 | 모델당 VRM 비용 | 사진당 VRM 비용 |
|---|---|---|---|---|
| 스타터 | 100 | $15 | $1.50 | $3.75 |
| 빌더 | 500 | $60 | $1.20 | $3.00 |
| 스케일 | 2,500 | $250 | $1.00 | $2.50 |
토큰은 변환이 생성될 때 차감되며 실패 시 자동으로 반환됩니다.
엔드포인트
| 메서드 및 경로 | 기능 |
|---|---|
POST /conversions | 모델 또는 사진에서 변환 시작 |
GET /conversions/{id} | 단일 변환 폴링 |
GET /conversions?limit=20 | 최신 변환, 최신순(최대 100개) |
GET /conversions/{id}/vrm | VRM 파일 |
GET /conversions/{id}/preview.mp4 | 모든 표정을 재생하는 비디오 |
GET /conversions/{id}/preview/{name}.png | 단일 스틸 이미지 |
DELETE /conversions/{id} | 변환 및 관련 파일 삭제 |
POST /pictures/fix | 사진만 다시 그리기 시작 |
GET /pictures/fix/{id} | 단일 다시 그리기 폴링 |
GET /pictures/fix/{id}/image | 다시 그린 PNG |
GET /account | 토큰 잔액, 가격 및 동시성 제한 |
POST /conversions
Multipart 필드:
| 필드 | |
|---|---|
file | .glb 또는 .vrm, 최대 100MB. 리깅되었거나 미리깅된 휴머노이드. |
image | file 대신 사용: .png 또는 .jpg, 최대 20MB, 서서 카메라를 정면으로 바라보는 단일 전체 캐릭터. |
name | 선택 사항. 변환에 지정할 이름. 기본값은 파일 이름입니다. |
fix | 선택 사항, 사진 전용. true: 사진 확인에서 문제가 발견되면 모델을 만들기 전에 사진이 전신 정면도로 다시 그려집니다. +2 API 토큰, 다시 그려질 때만 청구됩니다. |
force | 선택 사항, 사진 전용. true: 사진 확인을 건너뛰고 사진을 그대로 사용합니다. fix보다 우선 적용됩니다. 둘 다 사용하면 아무것도 확인하거나 다시 그리지 않습니다. |
사진 확인. 요금이 청구되기 전에 사진이 머리부터 발끝까지 카메라를 정면으로 바라보는 단일 전체 휴머노이드 캐릭터인지 확인합니다. 그렇지 않은 경우 422 picture_rejected 및 problems 목록(not_humanoid, multi_view, not_full_body, not_front, 각각 message 포함)과 함께 거부됩니다. 다른 사진을 보내거나, 동일한 사진에 fix=true 또는 force=true를 설정하여 보내세요. 이 확인은 권장 사항입니다. 사용 가능한 사진에 대해 잘못 판단할 수 있으며, 이 경우 force를 사용합니다. 확인을 실행할 수 없는 경우 사진은 그대로 통과됩니다.
선택적 헤더 Idempotency-Key: <any string up to 64 chars>는 재시도를 안전하게 만듭니다. 동일한 키를 사용한 두 번째 요청은 다른 변환을 만들고 요금을 청구하는 대신 첫 번째 변환을 반환합니다.
curl -s -X POST https://app.riggle3d.com/api/v1/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-H "Idempotency-Key: order-1042" \
-F file=@character.glb \
-F name=robot변환 객체와 함께 201을 반환합니다. 오류: 400 invalid_request, 400 unsupported_file, 401 unauthorized, 402 insufficient_tokens, 413 file_too_large, 422 picture_rejected, 429 too_many_active (계정당 3개의 변환 진행 중) 및 503 unavailable (사진 기능 꺼짐).
GET /conversions/{id}
변환 객체를 반환합니다. status가 processing 상태를 벗어날 때까지 3-5초마다 호출하세요.
GET /conversions?limit=20
최신 변환, 최신순. limit는 최대 100까지입니다. 응답은 {"object": "list", "data": [conversion, …]}입니다.
GET /conversions/{id}/vrm
VRM 파일. status가 succeeded가 될 때까지 409 not_ready로 응답합니다.
GET /conversions/{id}/preview.mp4
모든 표정이 재생되는 비디오입니다. VRM 뷰어를 열지 않고 결과를 확인할 때 사용하세요.
GET /conversions/{id}/preview/{name}.png
단일 스틸 이미지. name은 변환 객체의 preview_images 키 중 하나입니다.
DELETE /conversions/{id}
204를 반환합니다. 파일은 일주일 이내에 영구적으로 삭제됩니다. 아직 실행 중인 변환을 삭제해도 토큰은 반환되지 않습니다.
POST /pictures/fix
사진만 다시 그리기. Multipart 필드 image(.png 또는 .jpg, 최대 20MB), 선택적 name 및 선택적 Idempotency-Key 헤더. 항상 사진을 평범한 배경에 있는 캐릭터의 전신 정면도로 다시 그립니다. 먼저 확인하지 않습니다. 비용은 2 API 토큰이며, 수정이 이루어질 때 차감되고 사진이 반환되지 않으면 반환됩니다.
변환과 같은 작업입니다. 응답은 picture-fix 객체와 함께 201이며, 그 후 폴링합니다.
{"id": "5f0c…", "object": "picture_fix", "status": "processing",
"name": "hero.png", "cost": 2, "refunded": false,
"created_at": "2026-11-17T10:02:11Z", "finished_at": null,
"error": null, "image_url": null}status는 processing에서 succeeded 또는 failed로 변경됩니다. 수정은 일반적으로 1분 이내에 완료됩니다. 3-5초마다 폴링하세요. 실패 시 error는 {"code": "fix_failed", "message": "…"}가 되고 refunded는 true가 됩니다. image_url은 성공 시 설정됩니다.
오류: 400 invalid_request, 400 unsupported_file, 402 insufficient_tokens, 413 file_too_large, 429 too_many_active (계정당 3개의 수정 진행 중, 변환과 별도로 계산) 및 503 unavailable.
GET /pictures/fix/{id}
picture-fix 객체를 반환합니다. status가 processing 상태를 벗어날 때까지 3-5초마다 호출하세요.
GET /pictures/fix/{id}/image
다시 그린 PNG. status가 succeeded가 될 때까지 409 not_ready로 응답합니다. 사진은 7일 동안 보관되며, POST /conversions에 image로 바로 보낼 수 있습니다.
이 예제는 처음부터 끝까지 수정을 실행한 다음 결과를 변환합니다.
# 1. 다시 그리기 시작 (2 API 토큰)
fix=$(curl -s -X POST $API/pictures/fix \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F image=@character.png | jq -r .id)
# 2. 더 이상 처리 중이 아닐 때까지 폴링
until [ "$(curl -s $API/pictures/fix/$fix \
-H "Authorization: Bearer $RIGGLE_API_KEY" | jq -r .status)" != processing ]
do sleep 4; done
# 3. 다시 그린 PNG를 다운로드하고 확인
curl -s -o fixed.png $API/pictures/fix/$fix/image \
-H "Authorization: Bearer $RIGGLE_API_KEY"
# 4. 다른 사진처럼 전송 (25 API 토큰)
curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F image=@fixed.pngGET /account
{"object": "account", "api_tokens": 90,
"prices": {"model_to_vrm": 10, "image_to_vrm": 25, "fix_picture": 2},
"max_active_conversions": 3}변환 객체
{
"id": "0b8f6c0e-3f0e-4d8e-9a57-0c9a2f6f1c11",
"object": "conversion",
"status": "processing",
"stage": "building_vrm",
"name": "robot",
"input": "model",
"cost": 10,
"refunded": false,
"created_at": "2026-11-17T10:02:11Z",
"finished_at": null,
"error": null,
"warnings": [],
"vrm_url": null,
"preview_video_url": null,
"preview_images": {}
}status:processing, 그 다음succeeded또는failed.- 처리 중
stage:generating_model(사진만),rigging(미리깅된 모델만),marking_face,building_vrm. 변환이 완료되면null이 됩니다. input:model또는image.cost: 해당 작업에 사용된 API 토큰. 토큰이 반환되면refunded가true가 됩니다.error:null이거나, 변환이 실패했을 때{"code": "conversion_failed", "message": "…"}가 됩니다. 이 경우refunded는true가 됩니다.warnings: 문자열 목록. 아바타는 빌드되었지만 미리보기를 확인해야 합니다. 예를 들어, 얼굴 마킹의 신뢰도가 낮거나 표정소가 거의 움직이지 않을 수 있습니다.vrm_url,preview_video_url및preview_images({name: url})는 성공 시 설정됩니다. 이들은 절대 API URL이며 동일한Authorization헤더가 필요하므로 그대로 브라우저에 전달할 수 없습니다.
오류
모든 오류는 일치하는 HTTP 상태와 함께 동일한 형태를 가집니다:
{"error": {"code": "not_ready", "message": "…"}}| 코드 | HTTP | 상황 |
|---|---|---|
invalid_request | 400 | 요청이 여기에 설명된 형식 중 하나가 아님 |
unsupported_file | 400 | 업로드된 파일이 엔드포인트에서 허용하는 파일 형식이 아님 |
unauthorized | 401 | Authorization 헤더에 유효한 키가 없음 |
insufficient_tokens | 402 | API 토큰 부족. required와 available은 error 내의 code 옆에 위치함 |
not_found | 404 | 이 계정에 해당 변환이 없음 |
not_ready | 409 | status가 succeeded가 되기 전에 VRM 또는 다시 그린 사진을 요청함 |
file_too_large | 413 | 모델은 100MB 초과, 사진은 20MB 초과 |
picture_rejected | 422 | 사진이 사진 확인을 통과하지 못함. problems 목록과 함께 제공되며, 요금은 청구되지 않음 |
too_many_active | 429 | 계정에서 이미 3개의 변환 또는 3개의 사진 수정이 진행 중임. 둘은 별도로 계산됨 |
unavailable | 503 | 사진 기능이 꺼져 있음 |
402 오류는 다음과 같습니다:
{"error": {"code": "insufficient_tokens", "message": "…",
"required": 25, "available": 10}}그리고 422 오류는 다음과 같습니다:
{"error": {"code": "picture_rejected", "message": "…",
"problems": [{"code": "not_full_body", "message": "…"}]}}수락되었지만 완료될 수 없었던 변환은 HTTP 오류가 아닙니다. 이는 status가 failed이고, error.code가 conversion_failed로 설정되고 토큰이 반환된 변환입니다.
Python 예제
requests를 사용한 세 번의 호출:
import os, time, requests
API = "https://app.riggle3d.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['RIGGLE_API_KEY']}"}
with open("character.glb", "rb") as f:
r = requests.post(f"{API}/conversions", headers=HEADERS, files={"file": f})
if not r.ok:
raise SystemExit(r.json()["error"]["message"])
conv = r.json()
while conv["status"] == "processing":
time.sleep(4)
conv = requests.get(f"{API}/conversions/{conv['id']}", headers=HEADERS).json()
if conv["status"] == "failed":
raise SystemExit(conv["error"]["message"]) # 토큰은 이미 반환됨
for w in conv["warnings"]:
print("warning:", w) # 빌드되었지만 미리보기 확인 필요
vrm = requests.get(conv["vrm_url"], headers=HEADERS) # 절대 URL
with open("character.vrm", "wb") as out:
out.write(vrm.content)종속성이 전혀 없는 클라이언트를 원하시면 예제 리포지토리에 있는 것을 복사하세요.
Node 예제
Node 18 이상, 내장된 fetch, FormData, Blob 사용. .mjs 파일로 저장하세요:
import { readFile, writeFile } from "node:fs/promises";
const API = "https://app.riggle3d.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.RIGGLE_API_KEY}` };
const form = new FormData();
form.append("file", new Blob([await readFile("character.glb")]), "character.glb");
const res = await fetch(`${API}/conversions`, { method: "POST", headers, body: form });
if (!res.ok) throw new Error((await res.json()).error.message);
let conv = await res.json();
while (conv.status === "processing") {
await new Promise((r) => setTimeout(r, 4000));
conv = await (await fetch(`${API}/conversions/${conv.id}`, { headers })).json();
}
if (conv.status === "failed") throw new Error(conv.error.message); // 토큰은 이미 반환됨
for (const w of conv.warnings) console.warn("warning:", w); // 빌드되었지만 미리보기 확인 필요
const vrm = await fetch(conv.vrm_url, { headers }); // 절대 URL
await writeFile("character.vrm", Buffer.from(await vrm.arrayBuffer()));대신 사진으로 시작하려면 file 대신 image 필드를 보내세요. 그 이후의 모든 과정은 동일합니다. 이미지를 VRM으로 변환하는 API 페이지를 참조하세요.
출력 결과물
다음이 포함된 VRM 1.0 파일:
- 매핑된 휴머노이드 본;
- 다섯 가지 표정소:
aa,ih,ee,oh,ou; blink,blinkLeft및blinkRight;happy,angry및surprised;- 리그에 눈 뼈가 있는 경우 lookAt.
얼굴이 얼마나 잘 보이는지는 모델에 따라 다릅니다. 입을 벌리고 모델링된 캐릭터는 가장 자연스러운 입 모양을 제공하는 반면, 닫힌 입은 더 부드러운 움직임을 보입니다. 결과물을 확인해야 할 경우 warnings에 표시됩니다. 사용자에게 파일을 전달하기 전에 preview.mp4를 재생하여 확인하세요.
출력은 VRM 1.0 전용입니다. 52개의 ARKit 블렌드셰이프는 포함되지 않습니다.
제한 사항
- 입력:
.glb또는.vrm최대 100MB,.png또는.jpg최대 20MB. 파일은 요청 시 업로드되며 다른 전달 방법은 없습니다. - 동시성: 계정당 3개의 변환 진행 가능. 네 번째 요청은
429 too_many_active를 받게 되므로 하나가 끝날 때까지 기다리세요. 사진 수정은 변환과 별도로 3개까지의 자체 제한이 있습니다. - 시간: 리깅된 모델은 1-3분, 사진은 3-6분. 3-5초마다 폴링하세요.
- 캐릭터: 휴머노이드. 사진의 경우, 서서 정면을 바라보는 단일 전체 캐릭터.
- 삭제된 변환: 파일은 일주일 이내에 영구적으로 삭제됩니다.
작업 페이지: GLB를 VRM으로 변환하는 API, 이미지를 VRM으로 변환하는 API 및 API를 통해 VRM에 표정소 및 깜박임 추가하기. 대신 브라우저에서 수동으로 단일 모델을 변환하려면 GLB to VRM 변환기를 사용하세요.
크리에이터들이 자주 묻는 질문
무료 등급이 있나요?
아니요. 무료 API 토큰은 없습니다. 팩을 구매해야 키가 작동합니다. 팩은 100 토큰에 $15, 500 토큰에 $60, 2,500 토큰에 $250이며, 변환 실패 시 토큰은 자동으로 반환됩니다.
변환이 실패하면 제 토큰은 어떻게 되나요?
자동으로 반환됩니다. 변환 상태는 failed가 되고, error.code는 conversion_failed가 되며, refunded는 true가 됩니다. 유일한 예외는 아직 실행 중인 변환을 삭제하는 경우로, 이 경우에는 토큰이 반환되지 않습니다.
API 토큰은 Riggle 웹 앱의 토큰과 동일한가요?
아니요. API 토큰은 개발자 페이지에서 구매하는 별도의 잔액입니다. 웹 앱의 Studio 토큰으로는 API 호출 비용을 지불할 수 없으며, API 토큰으로는 웹 앱의 다운로드 비용을 지불할 수 없고, 둘은 교환할 수 없습니다.
API 토큰은 만료되나요?
아니요.
웹훅이 있나요?
아니요. API는 폴링 방식입니다. status가 succeeded 또는 failed가 될 때까지 3-5초마다 GET /conversions/{id}를 요청하세요.
SDK가 있나요?
설치할 패키지는 없습니다. github.com/riggle3d/glb-to-vrm의 예제 리포지토리에 프로젝트에 복사하여 사용할 수 있는 종속성 없는 Python 클라이언트, 종속성 없는 Node 클라이언트 및 curl 예제가 있습니다.
파일을 업로드하는 대신 URL을 전달할 수 있나요?
아니요. 모델이나 사진은 POST /conversions 요청 시 multipart/form-data로 업로드해야 합니다.
FBX를 보낼 수 있나요?
아니요. API는 모델의 경우 .glb와 .vrm, 사진의 경우 .png와 .jpg를 받습니다. 먼저 FBX를 바이너리 glTF(.glb)로 내보내세요(예: Blender 사용).
제 사진을 사용할 수 없는 경우 어떻게 되나요?
요금이 청구되기 전에 사진을 확인합니다. 머리부터 발끝까지 카메라를 정면으로 바라보는 단일 전체 휴머노이드 캐릭터가 아닌 경우, 요청은 문제 목록과 함께 422 picture_rejected를 받게 됩니다. 다른 사진을 보내거나, fix=true를 추가하여 먼저 전신 정면도로 다시 그리도록 하거나(2 API 토큰 추가, 다시 그릴 때만 청구됨), force=true를 추가하여 확인을 건너뛸 수 있습니다.
동시에 몇 개의 변환을 실행할 수 있나요?
계정당 3개입니다. 네 번째 POST /conversions 요청은 그중 하나가 끝날 때까지 429 too_many_active를 받게 됩니다.
결과가 좋은지 어떻게 알 수 있나요?
변환 객체의 warnings를 읽고 preview.mp4를 재생해 보세요. 경고는 아바타가 빌드되었지만, 예를 들어 얼굴이 낮은 신뢰도로 감지되었거나 표정소가 거의 움직이지 않는 등 확인이 필요한 사항이 있음을 의미합니다.
모델을 리깅해야 하나요?
아니요. 미리깅된 휴머노이드 .glb도 작동합니다. Riggle이 스켈레톤을 추가하며, 이 과정 동안 stage는 rigging으로 표시됩니다. 비용은 동일하게 10 API 토큰이며, 동일한 VRM 1.0으로 출력됩니다.