리깅 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
Meshy가 리깅할 수 있도록 공개적으로 접근 가능한 URL 또는 Data URI를 통해 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

리깅 작업 목록

호출자의 리깅 작업 목록을 페이지네이션하여 반환하며, 최신 항목이 먼저 나옵니다. page_num 및 page_size를 통한 표준 페이지네이션.

API를 통해 생성된 작업은 API를 통해 관리되며, 웹 앱의 내 자산에는 나타나지 않습니다. 더 이상 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
작업의 진행률입니다 (0-100). 시작되지 않았으면 0, 성공하면 100입니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시점의 타임스탬프(에포크 이후 밀리초)입니다.
타임스탬프는 1970년 1월 1일 UTC 이후 경과된 밀리초 수를 나타내며, RFC 3339 표준을 따릅니다. 예를 들어, 2023년 9월 1일 금요일 오후 12:00:00 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
}