애니메이션 API

사용 가능한 애니메이션을 검색하고 이를 rig가 적용된 캐릭터에 적용하기 위한 endpoint입니다.

POST/openapi/v1/animations

애니메이션 작업 생성

이 엔드포인트를 사용하면 이전에 리깅된 캐릭터에 애니메이션을 적용하는 새 작업을 생성할 수 있습니다 — 애니메이션 라이브러리의 프리셋 액션(action_id) 또는 Text to Motion API로 생성한 모션 클립(motion_task_id) 중 하나를 사용합니다. 후처리 옵션도 포함됩니다.

파라미터

Name
rig_task_id
Type
string
필수
Description
성공적으로 완료된 리깅 작업(POST /openapi/v1/rigging)의 id입니다. 이 작업에서 나온 캐릭터가 애니메이션 처리됩니다.
Name
action_id
Type
integer
Description
적용할 프리셋 애니메이션 액션의 식별자입니다. 사용 가능한 전체 애니메이션 목록은 애니메이션 라이브러리 참조를 확인하세요. action_id 또는 motion_task_id 중 정확히 하나만 제공해야 합니다.
Name
motion_task_id
Type
string
Description
프리셋 액션 대신 적용할, 성공적으로 완료된 Text to Motion 작업의 id입니다. 생성된 클립은 리깅된 캐릭터에 리타깃되며 클립은 생성 시점에 스냅샷이 저장되므로, 이후 소스 작업이 만료되거나 삭제되어도 이 작업에는 영향이 없습니다. 소스 작업의 에셋은 3일 동안 보관되므로, 만료되기 전에 클립을 적용하세요. 바이페드 리그가 필요합니다. action_id 또는 motion_task_id 중 정확히 하나만 제공해야 합니다.
Name
post_process
Type
object
Description
애니메이션 출력에 대한 선택적 후처리입니다. 생략하면 표준 애니메이션 파일을 받게 됩니다.

다음 경우에만 적용 post_process is set

Name
operation_type
Type
string
필수
Description
수행할 작업의 유형입니다. 사용 가능한 값: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
기본값 30
Description
목표 프레임 레이트입니다. operation_type이 change_fps인 경우에만 적용됩니다. 허용되는 값: 24, 25, 30, 60.

motion_task_id를 사용하면 리타깃 결과가 GLB 전용 애니메이션이 될 수 있습니다. post_process를 요청했는데 FBX를 사용할 수 없는 경우, 작업은 task_error로 실패하며 크레딧이 자동으로 환불됩니다. post_process 없이 요청한 경우 작업은 성공하지만 animation_fbx_url은 비어 있습니다.

반환 값

응답의 result 속성에는 새로 생성된 애니메이션 작업의 작업 id가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 파라미터 누락: rig_task_id가 누락되었거나, action_id와 motion_task_id 중 어느 것도 제공되지 않았습니다.
- 파라미터 충돌: action_id와 motion_task_id가 모두 제공되었습니다 — 두 값은 상호 배타적입니다.
- 유효하지 않은 리깅 작업: rig_task_id가 유효하지 않거나 실패했거나 존재하지 않는 작업을 참조합니다.
- 유효하지 않은 액션 ID: action_id가 유효한 애니메이션에 해당하지 않습니다.
- 모션 작업 준비되지 않음: motion_task_id 작업이 아직 SUCCEEDED 상태가 아닙니다.
- 지원되지 않는 리그: motion_task_id는 바이페드 리그가 필요하며, 쿼드러페드 리그는 거부됩니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
404 - Not Found
Description
rig_task_id로 지정된 리깅 작업을 찾을 수 없거나, motion_task_id로 지정된 모션 작업을 찾을 수 없거나, 모션 클립이 만료되었습니다(소스 작업 에셋은 3일 동안 보관됩니다).
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

GET/openapi/v1/animations/:id

애니메이션 작업 조회

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

매개변수

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

반환값

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

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/animations/:id

애니메이션 작업 삭제

이 엔드포인트는 관련된 모든 모델 및 데이터를 포함하여 애니메이션 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

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

반환값

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

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/animations

애니메이션 작업 목록 조회

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

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

Request

GET

/openapi/v1/animations

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

GET/openapi/v1/animations/:id/stream

애니메이션 작업 스트리밍

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

매개변수

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

반환값

애니메이션 작업 객체의 스트림을 Server-Sent Events 형태로 반환합니다.

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

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/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": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

애니메이션 태스크 객체

애니메이션 태스크 객체는 리깅된 캐릭터에 애니메이션을 적용하는 작업 단위를 나타냅니다.

속성

Name
id
Type
string
Description
태스크의 고유 식별자입니다.
Name
type
Type
string
Description
애니메이션 태스크의 유형입니다. 값은 animate입니다.
Name
status
Type
string
Description
태스크의 상태입니다. 가능한 값: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
태스크의 진행률(0-100)입니다.
Name
created_at
Type
timestamp
Description
태스크가 생성된 타임스탬프(에포크 이후 밀리초)입니다.
타임스탬프는 RFC 3339 표준을 따라 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타냅니다. 예를 들어, 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을 포함합니다.
- Name
  animation_glb_url
  Type
  string
  Description
  GLB 형식의 애니메이션에 대한 다운로드 가능한 URL입니다.
- Name
  animation_fbx_url
  Type
  string
  Description
  FBX 형식의 애니메이션에 대한 다운로드 가능한 URL입니다.
- Name
  processed_usdz_url
  Type
  string
  Description
  USDZ 형식으로 처리된 애니메이션에 대한 다운로드 가능한 URL입니다.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  FBX 형식으로 처리된 아마추어에 대한 다운로드 가능한 URL입니다.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  FPS가 변경된 애니메이션(예: change_fps 작업이 사용된 경우)의 FBX 형식 다운로드 가능한 URL입니다.
Name
preceding_tasks
Type
integer
Description
대기열에 있는 선행 태스크의 수입니다. 상태가 PENDING일 때만 의미가 있습니다.

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}