Animation API

Mga endpoint para sa pagtuklas ng mga available na Animation at paglalapat ng mga ito sa mga character na may rig.

POST/openapi/v1/animations

Create an Animation Task

Pinapayagan ng endpoint na ito na gumawa ka ng bagong task para maglapat ng animation sa isang karakter na na-rig na noon — maaaring isang preset action mula sa animation library (action_id) o isang motion clip na na-generate mo gamit ang Text to Motion API (motion_task_id). Kasama rito ang mga opsyon sa post-processing.

Mga Parameter

Name
rig_task_id
Type
string
Kinakailangan
Description
Ang id ng isang matagumpay na natapos na rigging task (mula sa POST /openapi/v1/rigging). Ang karakter mula sa task na ito ang bibigyan ng animation.
Name
action_id
Type
integer
Description
Ang identifier ng preset animation action na ilalapat. Tingnan ang Animation Library Reference para sa kumpletong listahan ng mga available na animation. Magbigay ng eksaktong isa sa action_id o motion_task_id.
Name
motion_task_id
Type
string
Description
Ang id ng isang matagumpay na natapos na Text to Motion task na ilalapat sa halip na isang preset action. Ang na-generate na clip ay ire-retarget sa naka-rig na karakter at ang clip ay kinukuhanan ng snapshot sa oras ng paggawa, kaya hindi apektado ang task na ito kahit mag-expire o matanggal ang source task nito sa hinaharap. Ang mga asset ng source task ay itinatago nang 3 araw — ilapat ang clip bago ito mag-expire. Nangangailangan ng biped rig. Magbigay ng eksaktong isa sa action_id o motion_task_id.
Name
post_process
Type
object
Description
Opsyonal na post-processing para sa output ng animation. Huwag isama ito para makatanggap ng standard na mga file ng animation.

Naaangkop lamang kapag post_process is set

Name
operation_type
Type
string
Kinakailangan
Description
Ang uri ng operasyong isasagawa. Mga available na value: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
default 30
Description
Ang target na frame rate. Naaangkop lamang kapag ang operation_type ay change_fps. Mga pinapayagang value: 24, 25, 30, 60.

Sa paggamit ng motion_task_id, maaaring makagawa ang retarget ng animation na GLB-only lamang. Kung humiling ka ng post_process at walang available na FBX, mabibigo ang task na may task_error at ang iyong credits ay awtomatikong ire-refund; kung walang post_process, magtatagumpay ang task at magiging walang laman ang animation_fbx_url.

Ibinabalik

Ang result property ng response ay naglalaman ng task id ng bagong ginawang animation task.

Mga Paraan ng Kabiguan

Name
400 - Bad Request
Description
Hindi tinatanggap ang request. Mga karaniwang sanhi:
- Kulang na parameter: kulang ang rig_task_id, o walang ibinigay na action_id o motion_task_id.
- Magkasalungat na mga parameter: parehong ibinigay ang action_id at motion_task_id — magkatunggali ang mga ito.
- Di-wastong rig task: Ang rig_task_id ay di-wasto o tumutukoy sa isang nabigo/hindi umiiral na task.
- Di-wastong action ID: Ang action_id ay hindi tumutugma sa isang wastong animation.
- Hindi pa handa ang motion task: ang task na motion_task_id ay hindi pa SUCCEEDED.
- Hindi suportadong rig: nangangailangan ang motion_task_id ng biped rig; tinatanggihan ang mga quadruped rig.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits para isagawa ang task na ito.
Name
404 - Not Found
Description
Hindi natagpuan ang rigging task na tinukoy ng rig_task_id, hindi natagpuan ang motion task na tinukoy ng motion_task_id, o nag-expire na ang motion clip (ang mga asset ng source task ay itinatago nang 3 araw).
Name
429 - Too Many Requests
Description
Lumampas ka na sa iyong rate limit.

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

Kunin ang isang Animation Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na kunin ang isang animation task gamit ang isang valid na task na id. Sumangguni sa The Animation Task Object para makita kung aling mga properties ang kasama.

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa animation task na kukunin.

Ibinabalik

Ang tugon ay naglalaman ng Animation Task object. Tingnan ang seksyong The Animation Task Object para sa mga detalye.

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

Mag-delete ng Animation Task

Ang endpoint na ito ay permanenteng nagde-delete ng isang animation task, kasama ang lahat ng kaugnay na models at data. Ang aksyong ito ay hindi na maaaring i-reverse.

Path Parameters

Name
id
Type
path
Description
Ang ID ng animation task na ide-delete.

Ibinabalik

Nagbabalik ng 200 OK kung matagumpay.

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

List Animation Tasks

Nagbabalik ng isang paginated na listahan ng mga animation task ng tumatawag, pinakabago muna. Standard pagination gamit ang page_num at page_size.

Pansinin na ang mga task na ginawa sa pamamagitan ng API ay pinamamahalaan sa pamamagitan ng API — hindi sila lumalabas sa My Assets ng web app. Gamitin ang endpoint na ito upang mahanap ang isang task na wala ka nang 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

I-stream ang Animation Task

Ang endpoint na ito ay nag-istream ng real-time na mga update para sa isang Animation task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier ng Animation task na i-istream.

Ibinabalik

Nagbabalik ng stream ng The Animation Task Objects bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, ang response stream ay maglalaman lamang ng kinakailangang mga field na progress at 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
}

Ang Animation Task Object

Ang Animation Task object ay kumakatawan sa unit ng trabaho para sa pag-apply ng animation sa isang rigged character.

Mga Properties

Name
id
Type
string
Description
Natatanging identifier para sa task.
Name
type
Type
string
Description
Uri ng Animation task. Ang value ay animate.
Name
status
Type
string
Description
Status ng task. Mga posibleng value: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress ng task (0-100).
Name
created_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan ginawa ang task.
Ang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, ayon sa RFC 3339 standard. Halimbawa, Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Naaangkop ito sa lahat ng timestamp sa Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan nagsimulang iproseso ang task. 0 kung hindi pa nagsisimula.
Name
finished_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan natapos ang task. 0 kung hindi pa tapos.
Name
expires_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan mag-expire ang mga asset na resulta ng task.
Name
task_error
Type
object
Description
Detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nagastos ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (nirefund ang credits kapag nabigo).
Name
result
Type
object
Description
Naglalaman ng mga output animation URL kung ang task ay SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  Downloadable URL para sa animation sa format na GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadable URL para sa animation sa format na FBX.
- Name
  processed_usdz_url
  Type
  string
  Description
  Downloadable URL para sa naprosesong animation sa format na USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Downloadable URL para sa naprosesong armature sa format na FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Downloadable URL para sa animation na may binagong FPS sa format na FBX (halimbawa, kung ginamit ang operation na change_fps).
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga nakaunang task sa queue. May kahulugan lamang kapag ang status ay 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
}