Unity 캐릭터 워크플로: GLB를 생성하고 리그 확인하기

1. 이미지 작업 만들기

API 키와 공개 이미지 URL을 설정한 뒤 작업 하나를 제출합니다. 응답은 비동기이므로 작업 ID를 보관하고 첫 작업이 처리 중일 때 두 번째 작업을 만들지 마세요.

export TO3D_KEY='YOUR_API_KEY'
export TO3D_IMAGE_URL='https://example.com/character.png'

TASK_JSON=$(curl --fail-with-body --silent --show-error \
  https://api.to3d.app/api/trellis/tasks \
  -H "x-api-key: $TO3D_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -cn --arg image "$TO3D_IMAGE_URL" \
    '{task_type:"image-to-3d",input:{image:$image}}')")
TASK_ID=$(jq -er '.id' <<<"$TASK_JSON")
printf 'Task: %s\n' "$TASK_ID"

2. 작업을 폴링하고 GLB 다운로드하기

같은 작업 ID를 `succeeded`, `failed` 또는 `canceled`가 될 때까지 폴링합니다. `status`가 `succeeded`가 되면 `.output.model_file`의 URL을 다운로드합니다.

curl --fail-with-body --silent --show-error \
  "https://api.to3d.app/api/trellis/tasks/$TASK_ID" \
  -H "x-api-key: $TO3D_KEY" | jq '{id,status,output,error}'

MODEL_URL=$(curl --fail-with-body --silent --show-error \
  "https://api.to3d.app/api/trellis/tasks/$TASK_ID" \
  -H "x-api-key: $TO3D_KEY" | jq -er '.output.model_file')
curl --fail --location --silent --show-error "$MODEL_URL" --output character.glb
[ "$(head -c 4 character.glb)" = 'glTF' ]

3. 별도의 휴머노이드 리그 요청하기

`character.glb`를 API가 접근할 수 있는 URL에 호스팅한 뒤 두 번째 작업을 제출합니다. 먼저 확인하려는 명명 규칙이 있다면 `mixamo`를 선택하세요. `https://api.to3d.app/api/skin_tokens/tasks/$RIG_ID`를 폴링하고 성공 후 `output.model_file`을 다운로드합니다.

export TO3D_MODEL_URL='https://example.com/character.glb'
RIG_JSON=$(curl --fail-with-body --silent --show-error \
  https://api.to3d.app/api/skin_tokens/tasks \
  -H "x-api-key: $TO3D_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -cn --arg model "$TO3D_MODEL_URL" \
    '{task_type:"rig",input:{model:$model,bone_names:"mixamo"}}')")
RIG_ID=$(jq -er '.id' <<<"$RIG_JSON")
printf 'Rig task: %s\n' "$RIG_ID"

4. Unity에서 파일 확인하기

다운로드한 GLB를 프로젝트에서 사용하는 Unity 패키지 또는 임포터로 가져옵니다. 모델 스케일, 머티리얼, 스켈레톤 매핑, 바인드 포즈, 애니메이션 클립을 확인합니다. Unity에서 매핑되지 않은 본이나 구성할 수 없는 아바타를 보고하면 프로젝트에서 리그 또는 매핑을 조정하고 간단한 포즈를 테스트하세요. API의 `mixamo` 레이블은 명명 옵션이며 TO3D가 Unity Humanoid 리타게팅을 인증한다는 뜻이 아닙니다.

• 생성된 GLB, 리깅된 GLB, Unity 임포트 결과를 별도 산출물로 보관하면서 자신의 캐릭터를 검증하세요.

샘플 증거의 범위 지키기

#56 샘플 검사에서는 공개 GLB 네 개 모두에서 스켈레톤 조인트, 스킨 웨이트, UV, 임베디드 PNG를 확인했습니다. 이는 해당 파일의 내용을 설명하는 증거입니다. 모든 새 입력이 잘 변형되거나 얼굴 형태를 포함하거나 수정 없이 임포트된다는 증거는 아닙니다.

• 네 샘플만으로 얼굴 형태, viseme, VRM 출력 또는 Unity 자동 리타게팅을 입증할 수 없습니다.