Rigging API

Rigging API를 사용하면 3D 휴머노이드 모델에 스켈레톤(아마추어)을 프로그래밍 방식으로 추가하고, 메시를 바인딩하여 애니메이션 적용 준비를 할 수 있습니다. 리깅된 캐릭터에 애니메이션을 적용하는 방법은 Animation API를 참고하세요.

현재 프로그래밍 방식의 리깅은 팔다리와 신체 구조가 명확하게 정의된 표준 휴머노이드(이족보행) 에셋에서만 제대로 작동한다는 점에 유의하시기 바랍니다.

POST/openapi/v1/rigging

리깅 작업 생성

이 엔드포인트를 사용하면 주어진 3D 모델에 대한 새로운 리깅 작업을 생성할 수 있습니다. 작업이 성공적으로 완료되면 표준 형식의 리깅된 캐릭터와 선택적으로 기본적인 걷기/달리기 애니메이션을 제공합니다.

이 작업은 백그라운드에서 실행됩니다. 일반적으로 소요되는 시간에 대해서는 처리 시간을 참조하세요.

현재 자동 리깅은 다음과 같은 모델에는 적합하지 않습니다:

텍스처가 적용되지 않은 메시
인간형이 아닌 asset
팔다리 및 신체 구조가 불분명한 인간형 asset

input_task_id를 사용할 때, 300,000개를 초과하는 면(face)을 가진 모델은 리깅을 지원하지 않습니다. 리깅 전에 리메시 API를 사용하여 면 수를 줄여 주세요.

model_url을 사용할 때, 캐릭터의 얼굴은 +Z 축(표준 glTF 전방 방향)을 향해야 합니다. 다른 축을 향하는 모델은 포즈 추정에 실패합니다.

파라미터

input_task_id 또는 model_url 중 하나만 필수입니다. 둘 다 제공된 경우 input_task_id가 우선순위를 가집니다.

Name
input_task_id
Type
string
필수
Description
리깅이 필요한 입력 작업입니다. 현재 텍스처가 적용된 인간형 모델을 지원합니다.

Name
model_url
Type
string
필수
Description
공개적으로 접근 가능한 URL 또는 Data URI를 통해 Meshy가 리깅할 3D 모델을 제공해 주세요. 현재 텍스처가 적용된 인간형 GLB 파일(.glb 형식)을 지원합니다.
최대 파일 크기: http 또는 https URL의 경우 400MB, data: URI의 경우 100MB.
100MB를 초과하면서 10,000,000개 이상의 면을 가진 파일은 400을 반환합니다. 면은 삼각형 단위로 계산되며, 두 번 이상 그려진 메시는 복사본마다 한 번씩 계산됩니다. 100MB를 초과하는 GLB는 Draco 압축을 사용해서는 안 됩니다.

Name
height_meters
Type
number
기본값 1.7
Description
캐릭터 모델의 대략적인 높이(미터 단위)입니다. 이는 스케일링 및 리깅 정확도에 도움이 됩니다. 양수여야 합니다.
Name
texture_image_url
Type
string
Description
모델의 UV 언랩된 베이스 컬러 텍스처 이미지입니다. 공개적으로 접근 가능한 URL 또는 Data URI입니다. 현재 .png 형식을 지원합니다.
최대 파일 크기: 20MB.

반환값

응답의 result 속성에는 새로 생성된 리깅 작업의 작업 id가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청을 수락할 수 없습니다. 일반적인 원인:
- 파라미터 누락: model_url 또는 input_task_id 중 하나를 제공해야 합니다.
- 잘못된 모델 형식: model_url이 지원되지 않는 확장자의 파일을 가리킵니다(.glb만 지원).
- 접근할 수 없는 URL: model_url을 다운로드할 수 없습니다.
- 모델 파일이 너무 큼: model_url 파일이 400MB(http 또는 https URL) 또는 100MB(data: URI)를 초과합니다.
- 면이 너무 많음: model_url 파일이 100MB를 초과하면서 10,000,000개 이상의 면을 가지고 있습니다. 면 수를 줄인 후 파일을 다시 전송하세요.
- 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하며 헤더를 읽을 수 없습니다. 예를 들어 Draco로 압축된 GLB인 경우입니다.
- 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하며 헤더에 확인해야 할 메시, 노드 또는 레코드가 너무 많습니다. 파일 내 객체 수를 줄인 후 다시 전송하세요.
- 이미지가 너무 큼: texture_image_url 이미지가 20MB를 초과합니다.
- 잘못된 입력 작업: input_task_id가 유효한 API 작업을 참조하지 않습니다.
- 면 수 초과: 입력 모델의 면이 300,000개를 초과합니다. 리깅 전에 리메시 API를 사용하여 면 수를 줄여 주세요.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
422 - Unprocessable Entity
Description
포즈 추정에 실패했습니다. 제공된 모델이 유효한 인간형 캐릭터가 아닐 수 있습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

Rigging 작업 조회하기

이 엔드포인트를 사용하면 유효한 작업 id를 통해 rigging 작업을 조회할 수 있습니다. 포함된 속성을 확인하려면 The Rigging Task Object를 참고하세요.

매개변수

Name
id
Type
path
Description
조회할 rigging 작업의 고유 식별자입니다.

반환값

응답에는 Rigging Task 객체가 포함됩니다. 자세한 내용은 The Rigging Task Object 섹션을 확인하세요.

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

Rigging 작업 삭제

이 엔드포인트는 연결된 모든 모델과 데이터를 포함하여 rigging 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

Name
id
Type
path
Description
삭제할 rigging 작업의 ID입니다.

작업 상태

아직 PENDING 상태인 작업은 삭제되며, 생성 시 소모된 크레딧은 환불됩니다.

이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다: 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업의 크레딧은 환불되지 않으므로, 실행 도중 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. SUCCEEDED, FAILED 또는 CANCELED 상태가 될 때까지 기다린 후 삭제하세요.

종료 상태(SUCCEEDED, FAILED 또는 CANCELED)인 작업은 환불 없이 삭제됩니다.

반환값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS 상태인 경우 409 Conflict를 반환합니다.

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/rigging

리깅 작업 목록 조회

호출자의 리깅 작업 목록을 최신순으로 페이지네이션하여 반환합니다. page_num과 page_size를 통한 표준 페이지네이션을 지원합니다.

API를 통해 생성된 작업은 API를 통해 관리되며, 웹 앱의 My Assets에는 표시되지 않습니다. 더 이상 ID를 가지고 있지 않은 작업을 찾으려면 이 엔드포인트를 사용하세요.

Request

GET

/openapi/v1/rigging

curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/rigging/:id/stream

리깅 작업 스트리밍

이 엔드포인트는 Server-Sent Events (SSE)를 사용하여 리깅 작업에 대한 실시간 업데이트를 스트리밍합니다.

매개변수

Name
id
Type
path
Description
스트리밍할 리깅 작업의 고유 식별자입니다.

반환값

Server-Sent Events 형태로 리깅 작업 객체의 스트림을 반환합니다.

PENDING 또는 IN_PROGRESS 상태의 작업의 경우, 응답 스트림에는 필요한 progress 및 status 필드만 포함됩니다.

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

리깅 작업 객체

리깅 작업 객체는 캐릭터 리깅 작업 단위를 나타냅니다.

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다.
Name
type
Type
string
Description
리깅 작업의 유형입니다. 값은 rig입니다.
Name
status
Type
string
Description
작업의 상태입니다. 가능한 값: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
작업의 progress (0-100)입니다. 시작되지 않은 경우 0, 성공한 경우 100입니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 타임스탬프(밀리초, epoch 기준)입니다.
타임스탬프는 RFC 3339 표준을 따라 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타냅니다. 예를 들어, 2023년 9월 1일 금요일 오후 12시 00분 00초 GMT는 1693569600000으로 표현됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
started_at
Type
timestamp
Description
작업이 처리를 시작한 타임스탬프(밀리초, epoch 기준)입니다. 시작되지 않은 경우 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 타임스탬프(밀리초, epoch 기준)입니다. 완료되지 않은 경우 0입니다.
Name
expires_at
Type
timestamp
Description
작업 결과 에셋이 만료되어 삭제될 수 있는 타임스탬프(밀리초, epoch 기준)입니다.
Name
task_error
Type
object
Description
실패한 작업에 대한 오류 세부 정보입니다. task_error 객체의 전체 참조는 오류를 참조하세요.
Name
consumed_credits
Type
integer
Description
이 작업에서 소비된 크레딧 수입니다. 작업 상태가 PENDING, IN_PROGRESS, 또는 SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 0을 반환합니다(실패 시 크레딧은 환불됩니다).
Name
result
Type
object
Description
작업이 SUCCEEDED인 경우 출력 에셋 URL을 포함하며, 그렇지 않으면 null입니다.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  FBX 형식의 리깅된 캐릭터를 다운로드할 수 있는 URL입니다.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  GLB 형식의 리깅된 캐릭터를 다운로드할 수 있는 URL입니다.
- Name
  basic_animations
  Type
  object (optional)
  Description
  기본 애니메이션에 대한 URL을 포함합니다. (예: generate_basic_animations가 암묵적으로 true이거나 기본적으로 활성화된 경우.)
  Name
  walking_glb_url
  Type
  string
  Description
  GLB 형식의 걷기 애니메이션(스킨 포함)을 다운로드할 수 있는 URL입니다.
  Name
  walking_fbx_url
  Type
  string
  Description
  FBX 형식의 걷기 애니메이션(스킨 포함)을 다운로드할 수 있는 URL입니다.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  GLB 형식의 걷기 애니메이션 아마추어를 다운로드할 수 있는 URL입니다.
  Name
  running_glb_url
  Type
  string
  Description
  GLB 형식의 달리기 애니메이션(스킨 포함)을 다운로드할 수 있는 URL입니다.
  Name
  running_fbx_url
  Type
  string
  Description
  FBX 형식의 달리기 애니메이션(스킨 포함)을 다운로드할 수 있는 URL입니다.
  Name
  running_armature_glb_url
  Type
  string
  Description
  GLB 형식의 달리기 애니메이션 아마추어를 다운로드할 수 있는 URL입니다.
Name
preceding_tasks
Type
integer
Description
대기열에서 선행 작업의 수입니다. 상태가 PENDING일 때만 의미가 있습니다.

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}