리깅 API

휴머노이드 3D 모델에 스켈레톤(아마추어)을 추가하고 메시를 바인딩하여 캐릭터가 애니메이션을 적용할 준비가 되도록 합니다. 리깅된 캐릭터에 애니메이션을 적용하려면 Animation API를 참조하세요.

리깅은 팔다리와 신체 구조가 명확하게 정의된 표준 휴머노이드(이족보행) 캐릭터에서만 잘 작동합니다.

POST/openapi/v1/rigging

리깅 작업 생성

3D 모델에 대한 리깅 작업을 생성합니다. 작업이 성공하면 표준 형식의 리깅된 캐릭터를 반환하며, 선택적으로 기본적인 걷기 및 달리기 애니메이션도 함께 반환합니다.

작업은 백그라운드에서 실행됩니다. 작업이 일반적으로 얼마나 걸리는지는 처리 시간을 참고하세요.

리깅은 다음 모델에는 적합하지 않습니다:

텍스처가 없는 메시
인간형이 아닌 asset
팔다리와 몸 구조가 명확하지 않은 인간형 asset

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"
}

파라미터

Name
input_task_id
Type
string
필수
Description
model_url을 보내지 않는 한 필수입니다. 리깅할 모델의 작업 ID입니다. Meshy는 텍스처가 적용된 인간형 모델을 지원합니다.
모델은 최대 380,000개의 삼각형(쿼드는 2개로 계산)을 가질 수 있으며, 이를 초과하면 400을 반환합니다. 한도를 넘지 않으려면 먼저 Remesh API를 target_polycount 300000 이하로 실행하거나, topology: quad인 경우 150000 이하로 실행하세요.

Name
model_url
Type
string
필수
Description
input_task_id를 보내지 않는 한 필수입니다. 리깅할 모델로, 공개 URL 또는 data URI 형식입니다. 둘 다 보내면 Meshy는 input_task_id를 사용합니다.
모델은 http 또는 https URL에서 최대 400MB, data URI로는 최대 100MB인 GLB(.glb) 파일이어야 합니다. 리깅은 텍스처가 적용된 인간형 모델을 지원합니다.
모델은 최대 380,000개의 삼각형(쿼드는 2개로 계산)을 가질 수 있으며, 이를 초과하면 400을 반환합니다. 한도를 넘지 않으려면 먼저 Remesh API를 target_polycount 300000 이하로 실행하거나, topology: quad인 경우 150000 이하로 실행하세요.
캐릭터의 얼굴은 표준 glTF 정면 방향인 +Z 축을 향해야 합니다. 다른 축을 향하는 모델은 포즈 추정이 실패합니다.
100MB를 초과하는 파일은 다음 규칙도 따라야 합니다:
- 최대 10,000,000개의 면을 가질 수 있습니다. 이를 초과하는 파일은 400을 반환합니다. Meshy는 면을 삼각형 단위로 계산하며, 여러 번 그려지는 메시는 사본마다 한 번씩 계산됩니다.
- Draco 압축을 사용해서는 안 됩니다.

Name
height_meters
Type
number
기본값 1.7
Description
캐릭터의 대략적인 키(미터 단위)입니다. Meshy는 이를 사용해 모델의 크기를 조정하고 더 정확하게 리깅합니다. 음수 값은 400을 반환합니다.
Name
texture_image_url
Type
string
⚠ 사용 중단
Description
모델에 자체 텍스처가 있는 경우에는 이 값을 생략하세요. 이 값이 없으면 Meshy는 model_url 파일에 포함된 텍스처나 입력 작업의 텍스처를 사용합니다. 이 값을 보내면 이 이미지가 리깅된 모델의 유일한 텍스처가 되며, 모델은 PBR 맵을 잃게 됩니다.
모델의 UV 언랩된 기본 색상 텍스처로, 공개 URL 또는 data URI 형식입니다. 이미지는 최대 20MB의 PNG 파일이어야 합니다. 다른 이미지 형식은 400을 반환합니다.

반환값

응답의 result 필드에는 새 리깅 작업의 ID가 담겨 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지는 발견된 문제를 설명합니다. 예를 들어:
- 파라미터 누락: model_url과 input_task_id 중 어느 것도 보내지 않았습니다.
- 잘못된 모델 형식: model_url 파일의 확장자가 지원되지 않습니다. .glb만 지원됩니다.
- 접근 불가능한 URL: Meshy가 model_url 파일을 다운로드할 수 없습니다.
- 모델 파일이 너무 큼: model_url 파일이 http 또는 https URL 기준 400MB를 초과하거나, data URI 기준 100MB를 초과합니다.
- 면이 너무 많음: model_url 파일이 100MB를 초과하며 10,000,000개가 넘는 면을 가지고 있습니다. 면 개수를 줄인 후 파일을 다시 보내세요.
- 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하며, Meshy가 헤더를 읽을 수 없습니다. 예를 들어 Draco로 압축된 GLB인 경우입니다.
- 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하며, 헤더에 확인해야 할 메시, 노드 또는 레코드가 너무 많습니다. 파일 내 객체 수를 줄인 후 다시 보내세요.
- 이미지가 너무 큼: texture_image_url 이미지가 20MB를 초과합니다.
- 잘못된 텍스처 형식: texture_image_url 이미지가 PNG 파일이 아닙니다.
- 잘못된 높이: height_meters가 음수입니다.
- 잘못된 입력 작업: input_task_id가 유효한 API 작업을 가리키지 않습니다.
- 입력 작업이 준비되지 않음: input_task_id 작업이 아직 SUCCEEDED 상태에 도달하지 않았습니다. 작업이 성공할 때까지 기다린 후 재시도하세요.
- 면 개수 초과: 입력 모델이 380,000개를 초과하는 삼각형(쿼드는 2개로 계산)을 가지고 있습니다. 모델을 리깅하기 전에 Remesh API를 target_polycount 300000 이하로 실행하거나, topology: quad인 경우 150000 이하로 실행하세요.
요청을 수정한 후 다시 보내세요. 오류를 참고하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
예를 들어:
- 크레딧 부족: 계정에 이 작업을 수행하기에 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 후 재시도하세요.
- 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 후 재시도하세요.
Name
403 - Forbidden
Description
input_task_id가 이 엔드포인트가 리깅할 수 없는 저부조(bas-relief) 모델입니다. 메시지는 This model type does not support this operation입니다. 다른 모델을 보내세요.
Name
404 - Not Found
Description
Meshy가 input_task_id 작업의 파일을 찾을 수 없습니다. 다음 중 하나에 해당합니다:
- Meshy가 작업의 expires_at 이후 작업 파일을 삭제했습니다. 작업을 다시 생성한 후 해당 작업의 ID를 보내세요.
- 작업에 리깅에 필요한 파일(예: 미리보기 이미지)이 없습니다(예: Convert 작업). 작업의 원본 작업을 리깅하거나, 모델을 model_url로 보내세요.
Name
422 - Unprocessable Entity
Description
포즈 추정에 실패했습니다. 모델이 유효한 인간형 캐릭터가 아닐 수 있습니다. 인간형 캐릭터 모델을 보내세요. model_url의 경우, 캐릭터가 +Z 축을 향하고 있는지도 확인하세요.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다. 잠시 기다린 후 재시도하세요. 속도 제한을 참고하세요.

GET/openapi/v1/rigging/:id

Rigging 작업 조회

ID로 Rigging 작업을 반환합니다.

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": null,
  "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=..."
    }
  }
}

매개변수

Name
id
Type
path
Description
생성 응답에서 제공된 작업 ID입니다.

반환값

Rigging 작업 객체를 반환합니다.

DELETE/openapi/v1/rigging/:id

리깅 작업 삭제

리깅 작업을 모델 및 데이터와 함께 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

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 keeps 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."
}

경로 매개변수

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

작업 상태

PENDING 상태의 작업을 삭제하면 작업을 생성할 때 사용한 크레딧이 환불됩니다.

IN_PROGRESS 상태의 작업은 삭제할 수 없습니다. 요청은 409 Conflict를 반환하며, 작업은 계속 실행됩니다. Meshy는 이미 시작된 작업에 대해서는 환불을 제공하지 않으므로, 해당 작업을 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. 작업이 SUCCEEDED, FAILED, 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)의 작업을 삭제해도 크레딧은 환불되지 않습니다.

반환값

작업이 삭제되면 200 OK를, 작업이 IN_PROGRESS 상태이면 409 Conflict를 반환합니다.

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)로 스트리밍합니다.

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.
// These examples are shortened. Each event holds the full task object.
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 event, with the same fields as the 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": null,
  "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?..."
    }
  }
}

Parameters

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

Returns

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

각 이벤트는 Get 엔드포인트가 반환하는 것과 동일한 형태로 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 결과 필드에 아직 값이 없습니다.

리깅 작업 객체

리깅 작업 객체는 하나의 캐릭터에 대한 리깅을 설명합니다. 작업이 성공했을 때의 상태, progress, 출력 파일을 담고 있습니다.

속성

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": null,
  "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=..."
    }
  }
}

Name
id
Type
string
Description
작업 ID입니다. 불투명한 문자열로 취급하고, 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 rig입니다.
Name
status
Type
string
Description
작업 상태이며, PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
progress
Type
integer
Description
작업이 얼마나 완료되었는지를 백분율로 나타냅니다. 작업이 시작되기 전까지는 0이고, 성공하면 100이 됩니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시각으로, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시각으로, 유닉스 밀리초 단위입니다. 작업이 시작되기 전까지는 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시각으로, 유닉스 밀리초 단위입니다. 작업이 완료되기 전까지는 0입니다.
Name
expires_at
Type
timestamp
Description
작업의 결과 파일이 만료되는 시각으로, 유닉스 밀리초 단위입니다. 이 시각 이후에는 Meshy가 파일을 삭제할 수 있습니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 세부 정보입니다. 상태가 FAILED가 아니면 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
작업에 사용된 크레딧 수입니다. 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. 작업이 실패하면 Meshy가 크레딧을 환불하므로 FAILED 작업의 경우 0입니다.
Name
result
Type
object
Description
출력 파일 URL입니다. 작업이 성공하기 전까지 각 URL은 빈 문자열이며, basic_animations는 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입니다.
  Name
  walking_glb_url
  Type
  string
  Description
  스킨이 적용된 걷기 애니메이션으로, GLB 파일입니다.
  Name
  walking_fbx_url
  Type
  string
  Description
  스킨이 적용된 걷기 애니메이션으로, FBX 파일입니다.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  걷기 애니메이션의 아마추어로, GLB 파일입니다.
  Name
  running_glb_url
  Type
  string
  Description
  스킨이 적용된 달리기 애니메이션으로, GLB 파일입니다.
  Name
  running_fbx_url
  Type
  string
  Description
  스킨이 적용된 달리기 애니메이션으로, FBX 파일입니다.
  Name
  running_armature_glb_url
  Type
  string
  Description
  달리기 애니메이션의 아마추어로, GLB 파일입니다.
Name
preceding_tasks
Type
integer
Description
대기열에서 이 작업보다 앞에 있는 작업의 수입니다. 이 값은 작업이 PENDING 상태일 때만 의미가 있습니다. 값이 0일 때는 이 필드가 생략됩니다.