리깅 API

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

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

POST/openapi/v1/rigging

리깅 작업 생성

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

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

텍스처가 적용되지 않은 메쉬
비휴머노이드 애셋
팔다리와 신체 구조가 명확하지 않은 휴머노이드 애셋

input_task_id를 사용할 때 300,000개를 초과하는 면이 있는 모델은 리깅을 지원하지 않습니다. 리깅 전에 면 수를 줄이려면 리메시 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 형식)을 지원합니다.

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

반환값

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

실패 모드

Name
400 - Bad Request
Description
요청을 수락할 수 없습니다. 일반적인 원인:
- 누락된 파라미터: model_url 또는 input_task_id 중 하나를 제공해야 합니다.
- 잘못된 모델 형식: model_url이 지원되지 않는 확장자의 파일을 가리킵니다(.glb만 지원).
- 접근할 수 없는 URL: model_url을 다운로드할 수 없습니다.
- 잘못된 입력 작업: 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

리깅 작업 조회

이 엔드포인트를 사용하면 유효한 작업 id가 주어졌을 때 리깅 작업을 조회할 수 있습니다. 포함되는 속성을 확인하려면 리깅 작업 객체를 참조하세요.

매개변수

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

반환값

응답에는 리깅 작업 객체가 포함됩니다. 자세한 내용은 리깅 작업 객체 섹션을 확인하세요.

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

리깅 작업 삭제

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

경로 매개변수

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

반환값

성공 시 200 OK를 반환합니다.

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

// Returns 200 Ok on success.

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
작업이 생성된 시점의 타임스탬프(에포크 이후 밀리초)입니다.
타임스탬프는 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타내며, RFC 3339 표준을 따릅니다. 예를 들어 2023년 9월 1일 금요일 12:00:00 PM GMT는 1693569600000으로 표시됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
started_at
Type
timestamp
Description
작업 처리가 시작된 시점의 타임스탬프(에포크 이후 밀리초)입니다. 시작되지 않았으면 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시점의 타임스탬프(에포크 이후 밀리초)입니다. 완료되지 않았으면 0입니다.
Name
expires_at
Type
timestamp
Description
작업 결과 애셋이 만료되어 삭제될 수 있는 시점의 타임스탬프(에포크 이후 밀리초)입니다.
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
}