이미지 VRM 변환 API — 이미지를 보내면 말하는 VRM 1.0이 돌아옵니다

단 한 번의 요청으로 캐릭터의 PNG 또는 JPG를 가져와 말하고 깜박이는 VRM 1.0으로 완성합니다. 3D 생성기, 자동 리거, 변환기를 직접 연결할 필요가 없습니다.

API 키 받기 사진당 25 API 토큰 · .png 또는 .jpg 최대 20MB · VRM 1.0 출력

API를 통해 이미지를 VRM으로 변환하려면, .png 또는 .jpg(최대 20MB)를 image 필드로 https://app.riggle3d.com/api/v1/conversions에 POST합니다. 5가지 표정소, 깜박임, 3가지 감정, 그리고 리그에 눈 뼈가 있는 경우 lookAt 기능이 포함된 캐릭터의 VRM 1.0(텍스처가 있는 3D 바디와 휴머노이드 본)을 받게 됩니다. 3-6분이 소요되며 비용은 25 API 토큰($2.50 ~ $3.75, 팩에 따라 다름)이며, 변환 실패 시 자동으로 반환됩니다. 요금이 청구되기 전에 사진을 확인합니다. 전체 정면 휴머노이드 모습이 아닌 사진은 422 picture_rejected로 거부되며, fix=true를 설정하면 2개의 추가 토큰으로 사진을 먼저 다시 그립니다. 사진은 평범한 배경에서 서서 카메라를 정면으로 바라보는 단일 전체 캐릭터를 보여주어야 합니다.

한 번의 호출 후 폴링

export RIGGLE_API_KEY=rgl_...
API=https://app.riggle3d.com/api/v1

# 1. 사진 전송 (25 API 토큰)
id=$(curl -s -X POST $API/conversions \
  -H "Authorization: Bearer $RIGGLE_API_KEY" \
  -H "Idempotency-Key: mascot-0001" \
  -F image=@character.png \
  -F name=mascot | jq -r .id)

# 2. 폴링: generating_model, 그 다음 marking_face, building_vrm
until [ "$(curl -s $API/conversions/$id \
  -H "Authorization: Bearer $RIGGLE_API_KEY" | jq -r .status)" != processing ]
do sleep 5; done

# 3. VRM 다운로드
curl -s -o mascot.vrm $API/conversions/$id/vrm \
  -H "Authorization: Bearer $RIGGLE_API_KEY"

모델 변환과의 유일한 차이점은 필드입니다: file 대신 image. 변환 객체는 input이 image로, cost가 25로 설정되어 반환되며, stage는 generating_model에서 시작됩니다. 오류를 포함한 다른 모든 것은 API 레퍼런스에 있습니다.

Node 18 이상:

import { readFile } 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("image", new Blob([await readFile("character.png")]), "character.png");
// form.append("fix", "true");   // 확인에서 문제가 발견되면 먼저 다시 그리기 (+2)
// form.append("force", "true"); // 또는 확인 건너뛰기

const res = await fetch(`${API}/conversions`, { method: "POST", headers, body: form });
const body = await res.json();
if (res.status === 422) console.log("사진 거부됨, 요금 미청구:", body.error.problems);
else if (res.status === 503) console.log("현재 사진 기능이 꺼져 있습니다");
else if (!res.ok) throw new Error(body.error.message);
else console.log(body.id, body.input, body.cost); // "image", 25

전체 클라이언트는 github.com/riggle3d/glb-to-vrm에 있습니다.

작동하는 사진 유형

3D 모델은 사진에 보이는 것만 가질 수 있으므로, 사진이 결과의 대부분을 결정합니다.

  • 단일 전체 캐릭터. 프레임 안에 머리부터 발끝까지. 초상화나 상반신 사진은 리깅할 다리가 없고, 두 캐릭터는 하나의 메시가 됩니다.
  • 서 있는 자세. 몸통과 팔이 융합되지 않도록 팔을 몸에서 뗀 채 똑바로 서 있어야 합니다.
  • 카메라를 정면으로 바라보는 자세. 측면이나 3/4 뷰가 아닌 정면 뷰.
  • 단색 배경. 바닥, 그림자, 소품 등 프레임 안의 다른 모든 것은 모델의 일부가 될 수 있습니다.
  • 입을 벌리고 있으면 도움이 됩니다. 입을 벌리고 있는 캐릭터는 가장 자연스러운 입 모양을 제공하며, 3D 모델은 사진에 보이는 것을 유지합니다. 입술을 다물고 그린 캐릭터도 변환되지만 입 움직임이 더 부드럽습니다.

.png 또는 .jpg, 최대 20MB. AI 이미지를 VRM 아바타로 변환 가이드에는 이 모든 것을 충족하는 사진 생성을 위한 참조 프롬프트가 있습니다.

거부된 사진: fix 및 force

요금이 청구되기 전에 사진이 머리부터 발끝까지 카메라를 정면으로 바라보는 단일 전체 휴머노이드 캐릭터인지 확인합니다. 그렇지 않은 경우 422 picture_rejected로 거부됩니다. 변환이 생성되지 않고 토큰이 사용되지 않으며, 오류에는 코드와 message가 포함된 problems 목록이 전달됩니다.

문제 코드확인 결과
not_humanoid휴머노이드 캐릭터가 아님
multi_view캐릭터 시트처럼 사진에 캐릭터의 여러 뷰가 있음
not_full_body머리부터 발끝까지 전신이 아님
not_front캐릭터가 카메라를 정면으로 바라보고 있지 않음

여기서 세 가지 옵션이 있습니다:

  • 다른 사진 보내기.
  • fix=true. 확인 시 문제가 발견되면 모델을 만들기 전에 사진이 전신 정면도로 다시 그려집니다. 이는 25개에 더해 2개의 API 토큰이 추가로 들며, 사진이 실제로 다시 그려질 때만 청구됩니다. 첫 요청 시 이 옵션을 설정하면 필요한 사진이 422 오류로 반환되는 일이 없습니다.
  • force=true. 확인을 건너뛰고 사진을 있는 그대로 사용합니다. fix보다 우선 적용됩니다. 둘 다 사용하면 아무것도 확인하거나 다시 그리지 않습니다.
# 사진을 확인하고, 문제가 발견되면 먼저 다시 그립니다
# 통과하면 25 API 토큰, 다시 그려야 했다면 27
curl -s -X POST $API/conversions \
  -H "Authorization: Bearer $RIGGLE_API_KEY" \
  -F image=@character.png \
  -F fix=true

# 확인을 건너뛰고 사진을 있는 그대로 사용합니다 (25 API 토큰)
curl -s -X POST $API/conversions \
  -H "Authorization: Bearer $RIGGLE_API_KEY" \
  -F image=@character.png \
  -F force=true

25개의 토큰을 사용하기 전에 다시 그린 사진을 보려면 두 단계로 진행하세요. POST /pictures/fix는 2개의 API 토큰으로 다시 그리기를 자체적으로 시작합니다. 변환과 같은 작업입니다. status가 succeeded가 될 때까지 GET /pictures/fix/{id}를 폴링하고(보통 1분 미만 소요), GET /pictures/fix/{id}/image에서 PNG를 다운로드합니다. PNG를 확인하고 괜찮으면 POST /conversions에 image로 보냅니다. fix=true와 달리, 먼저 확인하지 않고 항상 다시 그립니다. 다시 그린 사진은 7일 동안 보관되며, 수정 실패 시 토큰은 반환됩니다. 자세한 내용은 API 레퍼런스에 있습니다.

# 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

확인은 권장 사항입니다. 사용 가능한 사진에 대해 잘못 판단할 수 있으며, 이 경우 force를 사용합니다. 확인을 실행할 수 없는 경우 사진은 확인 없이 통과됩니다. 다시 그린 사진은 캐릭터의 새로운 그림이므로, 아바타를 사용자에게 보여주기 전에 미리보기를 확인하세요.

폴링 중 stage가 알려주는 것

  1. generating_model: 사진으로 3D 모델을 만드는 중입니다.
  2. rigging: 모델에 스켈레톤이 필요한 경우에만 표시됩니다.
  3. marking_face: 입과 눈을 찾는 중입니다.
  4. building_vrm: VRM 1.0을 완성하는 중입니다.

전체 과정은 3-6분 정도 걸립니다. 성공하면 VRM, 모든 표정을 재생하는 preview.mp4, 스틸 이미지, 그리고 확인이 필요한 사항이 있을 때 warnings를 받게 됩니다. 사진에서 생성하는 것은 직접 만든 모델을 변환하는 것보다 변동성이 크므로, 아바타를 사용자에게 보여주기 전에 미리보기를 재생해 보세요.

가격

팩API 토큰가격사진 → VRM 당
스타터100$15$3.75
빌더500$60$3.00
스케일2,500$250$2.50

사진 한 장당 25 API 토큰이며, 3D 모델과 VRM이 모두 포함됩니다. fix=true를 사용하면 다시 그려야 했던 사진은 2개가 더 추가되어 총 27 토큰이 됩니다. 이는 팩에 따라 $4.05, $3.24, $2.70입니다. 확인을 통과한 사진에는 추가 2 토큰이 청구되지 않습니다. 확인 자체는 요금이 청구되기 전에 실행되며, 변환이 어떤 단계에서든 실패하면 다시 그리기에 사용된 2개를 포함한 모든 토큰이 자동으로 반환됩니다.

이미지에 대해 POST /conversions가 503 unavailable로 응답하면 현재 사진 기능이 꺼져 있는 것입니다. 요금은 청구되지 않으며 모델 변환에는 영향을 미치지 않습니다.

대신 모델을 보내야 할 때

자체 생성기나 아티스트로부터 이미 캐릭터의 3D 모델을 가지고 있다면 GLB를 보내세요. 25개 대신 10개 토큰으로 더 빠르며, 몸체는 여러분이 만든 것과 정확히 동일합니다. GLB to VRM API를 참조하세요. 브라우저에서 수동으로 사진 한 장을 처리하려면 이미지 to VRM을 사용하세요.

자신만의 코드로 사진을 아바타로 변환하기

키를 만들고, 팩을 구매하고, 첫 사진을 전송하세요. 사진당 25 API 토큰이며, 변환 실패 시 반환됩니다.

API 키 받기

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

API를 통한 이미지 to VRM 비용은 얼마인가요?

사진당 25 API 토큰입니다: 스타터 팩은 $3.75, 빌더 팩은 $3.00, 스케일 팩은 $2.50입니다. 이는 3D 모델과 VRM을 모두 포함하며, 변환 실패 시 반환됩니다. fix=true로 다시 그린 사진은 2 토큰이 더 듭니다.

시간이 얼마나 걸리나요?

3분에서 6분입니다. status가 succeeded 또는 failed가 될 때까지 3-5초마다 GET /conversions/{id}를 폴링하세요.

어떤 이미지 형식과 크기가 허용되나요?

.png 및 .jpg, 최대 20MB, multipart 필드 image로 업로드됩니다.

422 picture_rejected는 무슨 뜻인가요?

사진 확인 결과, 사진이 머리부터 발끝까지 카메라를 정면으로 바라보는 단일 전체 휴머노이드 캐릭터가 아니라는 것을 발견했습니다. 아무것도 생성되거나 청구되지 않았습니다. problems 목록이 그 이유를 알려줍니다: not_humanoid, multi_view, not_full_body 또는 not_front, 각각 메시지와 함께. 다른 사진을 보내거나, 동일한 사진에 fix=true 또는 force=true를 설정하여 보내세요.

fix=true는 무엇을 하며, 비용은 얼마인가요?

사진 확인 시 문제가 발견되면, 3D 모델을 만들기 전에 사진이 전신 정면도로 다시 그려집니다. 총 27개로 2개의 API 토큰이 추가되며, 사진이 실제로 다시 그려질 때만 청구됩니다. 확인을 통과한 사진은 평소와 같이 25개 토큰이 비용으로 청구됩니다.

확인에서 제가 괜찮다고 알고 있는 사진을 거부했습니다. 이제 어떻게 해야 하나요?

force=true를 설정하여 다시 보내세요. 확인은 권장 사항이며 사용 가능한 사진에 대해 잘못 판단할 수 있습니다. force는 이를 건너뛰고 사진을 있는 그대로 사용합니다.

3D 모델이 만들어지기 전에 다시 그린 사진을 볼 수 있나요?

네. POST /pictures/fix는 2개의 API 토큰으로 다시 그리기를 자체적으로 시작합니다. status가 succeeded가 될 때까지(보통 1분 미만) GET /pictures/fix/{id}를 폴링하고, GET /pictures/fix/{id}/image에서 PNG를 다운로드하여 확인한 다음, POST /conversions에 image로 보냅니다. fix=true를 사용하면 확인, 다시 그리기, 변환이 한 번의 호출로 이루어지며, 미리보기에서 처음으로 결과를 볼 수 있습니다. 독립 실행형 수정은 항상 다시 그리며, 사진이 반환되지 않으면 토큰이 환불됩니다.

초상화나 얼굴 사진을 사용할 수 있나요?

아니요. 사진에는 서서 카메라를 정면으로 바라보는 단일 전체 캐릭터가 필요합니다. VRM은 완전한 휴머노이드이며, 초상화에는 리깅할 몸체가 없습니다.

이미지 URL이나 텍스트 프롬프트를 전달할 수 있나요?

아니요. API는 업로드된 .png 또는 .jpg를 받습니다. 원하는 이미지 모델로 사진을 생성한 다음 업로드하세요.

중간 3D 모델을 다운로드할 수 있나요?

API는 VRM, 미리보기 비디오 및 스틸 이미지를 반환합니다. VRM 자체는 바이너리 glTF이므로, VRM 확장 기능을 읽지 않는 도구에서도 동일한 파일이 GLB로 열립니다.

시험해 볼 수 있는 무료 토큰이 있나요?

아니요. 무료 API 토큰은 없습니다. 팩을 구매해야 키가 작동합니다. 사진 한 장당 25 토큰이 들며, 변환 실패 시 반환됩니다.

503 unavailable은 무슨 뜻인가요?

현재 사진 기능이 꺼져 있습니다. 아무것도 생성되거나 청구되지 않았습니다. file 필드를 사용한 모델 변환은 여전히 작동합니다.

실제 사람의 사진을 사용할 수 있나요?

해당 인물의 동의가 있는 경우에만 가능하며, 결과는 덜 기대하는 것이 좋습니다. 3D 단계는 깔끔한 형태의 양식화된 캐릭터에서 가장 잘 작동하며, 프레이밍 규칙은 동일합니다.

가이드