Animation API

Mga endpoint para sa paghahanap ng mga available na Animation at sa pag-apply nito sa mga character na may rig.

POST/openapi/v1/animations

Create an Animation Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na gumawa ng bagong task upang mag-apply ng animation sa isang character na dati nang na-rig — isang preset action mula sa animation library (action_id), ilang preset actions na pinagsama sa isang file (action_ids), o isang motion clip na iyong nabuo 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 character mula sa task na ito ang bibigyan ng animation.
Name
action_id
Type
integer
Description
Ang identifier ng preset animation action na i-a-apply. Tingnan ang Animation Library Reference para sa kumpletong listahan ng mga available na animation. Magbigay ng eksaktong isa sa action_id, action_ids o motion_task_id.
Name
action_ids
Type
array of integers
Description
Ilang preset animation actions na i-a-apply nang sabay-sabay, na ibabalik bilang iisang file na naglalaman ng isang animation clip para sa bawat action — kapaki-pakinabang para sa pagpapatakbo ng isang character mula sa isang state machine sa isang game engine. Magbigay ng 1 hanggang 10 action_id na mga value mula sa Animation Library Reference; kailangang natatangi ang mga id. Nagkakahalaga ng 3 credits bawat action. Magbigay ng eksaktong isa sa action_id, action_ids o motion_task_id.
Ang pagpasa ng action_ids na may iisang elemento ay katumbas ng pagpasa sa value na iyon bilang action_id.
Name
motion_task_id
Type
string
Description
Ang id ng isang matagumpay na natapos na Text to Motion task na i-a-apply sa halip na isang preset action. Ang nabuong clip ay ire-retarget papunta sa naka-rig na character at kinukuhanan ito ng snapshot sa oras ng paggawa, kaya hindi apektado ang task na ito kung ang source task ay mag-expire o mabura sa ibang pagkakataon. Ang mga asset ng source task ay pinapanatili nang 3 araw — i-apply ang clip bago ito mag-expire. Nangangailangan ng biped rig. Magbigay ng eksaktong isa sa action_id, action_ids o motion_task_id.
Name
post_process
Type
object
Description
Opsyonal na post-processing para sa animation output. Alisin ito upang makatanggap ng mga karaniwang animation file.

Naaangkop lamang kapag post_process is set

Name
operation_type
Type
string
Kinakailangan
Description
Ang uri ng operasyon na isasagawa. Available na mga 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. Pinapayagang mga value: 24, 25, 30, 60.

Gamit ang action_ids, ang task ay nagbabalik ng isang pinagsamang file sa halip na isang file bawat action: ang animation_glb_url at animation_fbx_url ay bawat isa'y tumuturo sa iisang asset na naglalaman ng bawat hiniling na action bilang hiwalay na clip.

Pagkakasunud-sunod ng Clip: ang pagkakasunud-sunod ng array na action_ids, hindi ang numerical na pagkakasunud-sunod ng mga id.
Mga Pangalan ng Clip: ang pangalan ng animation sa library, na tumutugma sa mga pangalang nakukuha mo kapag nag-export ng lahat ng animation ng isang character bilang iisang file mula sa Meshy web app. Kung dalawang hiniling na id ang nagreresulta sa parehong pangalan ng clip, ang huli ay bibigyan ng suffix na kanyang action_id upang manatiling natatangi ang mga pangalan.
Post-processing: inaaplay sa pinagsamang file, hindi sa mga indibidwal na clip.

Gamit ang motion_task_id, maaaring makagawa ang retarget ng animation na GLB lamang. Kung humiling ka ng post_process at walang available na FBX, ang task ay mabibigo na may task_error at awtomatikong maisasauli ang iyong mga credits; kung walang post_process, matagumpay ang task at magiging walang laman ang animation_fbx_url.

Ibinabalik

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

Mga Paraan ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang mga sanhi:
- Nawawalang parameter: nawawala ang rig_task_id, o wala sa action_id, action_ids at motion_task_id ang ibinigay.
- Nagkakasalungat na mga parameter: higit sa isa sa action_id, action_ids at motion_task_id ang ibinigay — 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 isang action_id — o isang entry ng action_ids — ay hindi tumutugma sa isang wastong animation.
- Sobra-sobrang actions: Ang action_ids ay naglalaman ng higit sa 10 id.
- Duplicate na actions: Ang action_ids ay naglalaman ng parehong id nang higit sa isang beses.
- Hindi pa handa ang motion task: hindi pa SUCCEEDED ang task na motion_task_id.
- 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 upang isagawa ang task na ito.
Name
404 - Not Found
Description
Ang rigging task na tinukoy ng rig_task_id ay hindi natagpuan, ang motion task na tinukoy ng motion_task_id ay hindi natagpuan, o ang motion clip ay nag-expire na (ang mga asset ng source task ay pinapanatili nang 3 araw).
Name
429 - Too Many Requests
Description
Nalampasan mo na ang 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 several preset actions and get one file with one clip per 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",
    "action_ids": [10, 25, 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

Delete an Animation Task

Ang endpoint na ito ay permanenteng nagtatanggal ng isang animation task, kasama ang lahat ng kaugnay na modelo at data. Hindi na maibabalik ang aksyong ito.

Path Parameters

Name
id
Type
path
Description
Ang ID ng animation task na tatanggalin.

Katayuan ng Task

Ang task na PENDING pa ay tatanggalin at ang mga credits na nagamit noong paglikha nito ay ire-refund.

Ang task na IN_PROGRESS na ay hindi na maaaring tanggalin: tatanggihan ang request na may 409 Conflict at magpapatuloy ang pagtakbo ng task. Ang mga credits para sa isang task na naisimulan na ng worker ay hindi na maaaring i-refund, kaya ang pagtanggal dito habang tumatakbo ay magiging sanhi ng pagkawala ng credits at ng resulta. Hintayin muna itong makarating sa SUCCEEDED, FAILED, o CANCELED, bago ito tanggalin.

Ang task na nasa terminal state (SUCCEEDED, FAILED, o CANCELED) ay tatanggalin nang walang refund.

Mga Ibabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag IN_PROGRESS ang task.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left 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."
}

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
}

The Animation Task Object

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

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. Posibleng mga 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 isang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, alinsunod sa RFC 3339 na standard. Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay naaangkop 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-e-expire ang mga resultang asset ng task.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga task na nabigo. Tingnan ang Errors para sa buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na ginamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga task na FAILED (irerefund ang credits kapag nabigo).
Name
result
Type
object
Description
Naglalaman ng mga URL ng output animation kung ang task ay SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  Downloadable URL para sa animation sa GLB format. Para sa task na ginawa gamit ang action_ids, ang iisang file na ito ay naglalaman ng bawat hiniling na action bilang hiwalay na clip.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadable URL para sa animation sa FBX format. Para sa task na ginawa gamit ang action_ids, ang iisang file na ito ay naglalaman ng bawat hiniling na action bilang hiwalay na clip.
- Name
  processed_usdz_url
  Type
  string
  Description
  Downloadable URL para sa naiprosesong animation sa USDZ format.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Downloadable URL para sa naiprosesong armature sa FBX format.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Downloadable URL para sa animation na may binagong FPS sa FBX format (hal., kung ginamit ang operation na change_fps).
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task sa queue. May kahulugan lamang kung 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
}

GET/openapi/v1/animations/library

List Animations

Nagbabalik ng bawat animation sa library, nakaayos ayon sa action_id. Ang tugon ay isang kumpletong listahan sa halip na isang page, kaya sapat na ang isang tawag upang mapuno ang isang action picker. Nililimitahan ng mga filter ang resulta; huwag isama ang mga ito upang makuha ang lahat.

Upang tingnan ang parehong catalogue sa mata, na may animated preview ng bawat action, tingnan ang Animation Library reference.

Ang endpoint na ito ay libre — hindi ito gumagamit ng credits.

Mga Parameter

Name
search
Type
string
Description
Case-insensitive na substring match sa name o key. Literal ang pagtutugma, kaya ang % at _ ay ordinaryong karakter sa halip na wildcard.
Name
category
Type
string
Description
Eksaktong tugma sa category.
Mga available na value:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Eksaktong tugma sa sub_category. Tinatanggap nang mag-isa — hindi natatangi ang mga pangalan ng sub-category sa iba't ibang category (Transitioning ay makikita kapwa sa ilalim ng Fighting at DailyActions), kaya kung walang category, ang filter ay tumutugma sa sub-category na iyon saan man ito lumitaw.
Name
action_ids
Type
string
Description
Listahan ng mga value ng action_id na pinaghihiwalay ng kuwit na ibabalik, para sa paglutas ng mga tiyak na id sa halip na pag-browse. Tumatanggap ng pinakamarami 200 id. Ang mga id na walang dalang animation ay simpleng wala sa tugon, kaya magagamit mo rin ito upang tingnan kung available pa ang mga id na naka-imbak mo.

Pagsasama-sama ng mga filter

Inilalapat ang mga filter nang sabay-sabay — ang bawat isa ay lalo pang naglilimita sa resulta, kaya ang isang animation ay maibabalik lamang kung natutugunan nito ang lahat ng ito. Sa loob ng iisang filter, maraming value ang tumutugma sa alinman sa mga ito: ang search ay tumutugma sa name o key, at ang action_ids ay tumutugma sa anumang id sa listahan.

Ibig sabihin, ang isang kombinasyon na walang overlap ay nagbabalik ng walang laman na array sa halip na isang error. Ang Action 92 ay "Double Combo Attack", isang Fighting na animation:

?action_ids=92&category=Fighting ay nagbabalik ng action 92.
?action_ids=92&category=Dancing ay nagbabalik ng [] — hindi ito isang Dancing na animation.
?action_ids=92&search=walk ay nagbabalik ng [] — hindi tumutugma ang pangalan nito sa walk.

Upang kunin ang mga tiyak na animation anuman ang kanilang category, ipasa ang action_ids nang mag-isa.

Mga Ibinabalik

Nagbabalik ng listahan ng The Animation Objects.

Ang bawat action_id na naibalik dito ay tinatanggap ng Create an Animation Task sa itaas, at bawat id na tinatanggap nito ay naibabalik dito. Ang mga retirado nang animation ay wala sa pareho. Kung nag-cache ka ng library, i-refresh ito paminsan-minsan upang ang isang retirado nang id ay hindi manatili sa iyong picker.

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

The Animation Object

Name
action_id
Type
integer
Description
Ang value na ipapasa bilang action_id kapag gumagawa ng animation task. Natatangi at stable, ngunit hindi magkakasunod-sunod — ang mga retirado nang animation ay nag-iiwan ng agwat sa numbering, kaya huwag kailanman ipagpalagay na valid ang buong range ng mga id.
Name
name
Type
string
Description
Human-readable na label, para sa display. Hindi natatangi: may mga animation na magkapareho ang pangalan ngunit magkaiba ang variant, kaya gamitin ang action_id o key bilang identity.
Name
key
Type
string
Description
Natatangi at stable na slug para sa animation. Gamitin ito kung kailangan mo ng non-numeric na identifier bilang key para sa iyong sariling storage.
Name
category
Type
string
Description
Pangunahing grouping, hal. Fighting.
Name
sub_category
Type
string
Description
Grouping sa loob ng category, hal. AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL ng animated GIF na nagpapakita ng preview ng action, angkop para direktang i-render sa sarili mong picker.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}