Riggle VRM API — 레퍼런스

단일 REST API로 리깅 여부와 관계없이 3D 캐릭터 또는 캐릭터 사진을 가져와 말하고 깜박이는 VRM 1.0을 반환합니다. 이 페이지는 인증, 가격, 모든 엔드포인트, 변환 객체 및 오류에 대한 전체 레퍼런스입니다.

API 키 받기 모델당 $1부터 · .glb, .vrm, .png 또는 .jpg 입력 · 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, 리깅 여부 무관) → VRM10
사진(.png / .jpg) → 3D 모델 → VRM25
...사진을 먼저 다시 그리는 경우(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}/vrmVRM 파일
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. 리깅되었거나 미리깅된 휴머노이드.
imagefile 대신 사용: .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.png

GET /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_request400요청이 여기에 설명된 형식 중 하나가 아님
unsupported_file400업로드된 파일이 엔드포인트에서 허용하는 파일 형식이 아님
unauthorized401Authorization 헤더에 유효한 키가 없음
insufficient_tokens402API 토큰 부족. required와 available은 error 내의 code 옆에 위치함
not_found404이 계정에 해당 변환이 없음
not_ready409status가 succeeded가 되기 전에 VRM 또는 다시 그린 사진을 요청함
file_too_large413모델은 100MB 초과, 사진은 20MB 초과
picture_rejected422사진이 사진 확인을 통과하지 못함. problems 목록과 함께 제공되며, 요금은 청구되지 않음
too_many_active429계정에서 이미 3개의 변환 또는 3개의 사진 수정이 진행 중임. 둘은 별도로 계산됨
unavailable503사진 기능이 꺼져 있음

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부터 시작하며, 변환 실패 시 토큰은 반환됩니다.

API 키 받기

크리에이터들이 자주 묻는 질문

무료 등급이 있나요?

아니요. 무료 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으로 출력됩니다.

가이드