Ireretiro ang lowpoly sa Oct 30, 2026. Lumipat ng modelo bago ang mga petsang ito para maiwasan ang mga error sa request.

Animation API

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


POST/openapi/v1/animations

Create an Animation Task

Ang endpoint na ito ay nagbibigay-daan sa iyong gumawa ng bagong gawain upang maglapat ng animation sa isang karakter na naunang na-rig — isang preset action mula sa animation library (action_id), ilang preset action na pinagsama sa isang file (action_ids), o isang motion clip na nabuo mo gamit ang Text to Motion API (motion_task_id). Kasama rito ang mga opsyon sa post-processing.

Tumatakbo ang gawain sa background. Para sa karaniwang tagal nito, tingnan ang Processing Times.

Mga Parameter

  • Name
    rig_task_id
    Type
    string
    Kinakailangan
    Description

    Ang id ng isang matagumpay na nakumpletong rigging task (mula sa POST /openapi/v1/rigging). Ang karakter mula sa gawaing 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, action_ids o motion_task_id.

  • Name
    action_ids
    Type
    array of integers
    Description

    Ilang preset animation action na ilalapat nang sabay-sabay, na ibabalik bilang iisang file na naglalaman ng isang animation clip kada action — kapaki-pakinabang para sa pagpapatakbo ng isang karakter mula sa isang state machine sa isang game engine. Magbigay ng 1 hanggang 10 action_id na mga halaga mula sa Animation Library Reference; dapat natatangi ang mga id. Nagkakahalaga ng 3 credits kada 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 ng halagang iyon bilang action_id.

  • Name
    motion_task_id
    Type
    string
    Description

    Ang id ng isang matagumpay na nakumpletong Text to Motion task na ilalapat sa halip na isang preset action. Ang nabuong clip ay nire-retarget sa na-rig na karakter at ang clip ay kinukunan ng snapshot sa oras ng paggawa, kaya hindi naaapektuhan ang gawaing ito kung mamaya ay mag-expire o matanggal ang source task. Ang mga asset ng source task ay pinapanatili nang 3 araw — ilapat 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. Laktawan ito upang matanggap ang mga karaniwang animation file.

Naaangkop lamang kapag post_process is set
  • Name
    operation_type
    Type
    string
    Kinakailangan
    Description

    Ang uri ng operasyong isasagawa. Mga available na halaga: 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 halaga: 24, 25, 30, 60.

Mga Ibinabalik

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

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang kahilingan. Mga karaniwang dahilan:

    • Nawawalang parameter: nawawala ang rig_task_id, o walang nabigay na alinman sa action_id, action_ids at motion_task_id.
    • Mga magkasalungat na parameter: higit sa isa sa action_id, action_ids at motion_task_id ang ibinigay — magkakaiba ang mga ito at hindi maaaring sabay-sabay gamitin.
    • Di-wastong rig task: Ang rig_task_id ay hindi wasto o tumutukoy sa isang nabigo/hindi umiiral na gawain.
    • Di-wastong action ID: Ang isang action_id — o isang entry ng action_ids — ay hindi tumutugma sa isang wastong animation.
    • Masyadong maraming action: ang action_ids ay naglalaman ng higit sa 10 id.
    • Duplicate na mga action: ang action_ids ay naglalaman ng parehong id nang higit sa isang beses.
    • Hindi pa handa ang motion task: ang gawaing 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. Mangyaring tingnan ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat ang credits upang isagawa ang gawaing 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 pinapanatili 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 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 id. Sumangguni sa The Animation Task Object upang makita kung aling mga property 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

Permanenteng binubura ng endpoint na ito ang isang animation task, kasama na ang lahat ng kaugnay na mga modelo at data. Hindi na maaaring bawiin ang aksyong ito.

Mga Path Parameter

  • Name
    id
    Type
    path
    Description

    Ang ID ng animation task na ide-delete.

Katayuan ng Task

Ang isang task na PENDING pa ay dine-delete at ang mga credits na nagastos noong oras ng paggawa nito ay ire-refund.

Ang isang task na IN_PROGRESS na ay hindi maaaring i-delete: tatanggihan ang request na may 409 Conflict at magpapatuloy ang pagtakbo ng task. Ang mga credits para sa isang task na nasimulan na ng worker ay hindi na maaaring i-refund, kaya ang pag-delete dito habang tumatakbo ay magiging dahilan ng pagkawala ng iyong credits at ng resulta. Hintaying maabot nito ang SUCCEEDED, FAILED o CANCELED, bago ito i-delete.

Ang isang task na nasa terminal state (SUCCEEDED, FAILED o CANCELED) ay dine-delete nang walang refund.

Ibinabalik

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

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 ito ng pagination na listahan ng mga animation task ng tumatawag, pinakabago muna. Standard na pagination gamit ang page_num at page_size.

Pansinin na ang mga task na nilikha sa pamamagitan ng API ay pinamamahalaan sa pamamagitan ng API — hindi ito lumalabas sa My Assets ng web app. Gamitin ang endpoint na ito upang hanapin ang isang task na hindi mo na alam ang 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 nagsa-stream 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 para sa Animation task na i-stream.

Ibinabalik

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

Para sa mga task na nasa PENDING o IN_PROGRESS, ang response stream ay magsasama lamang ng mga kinakailangang 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 yunit ng trabaho para sa paglalapat ng animation sa isang rigged na karakter.

Mga Property

  • 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 nilikha ang task.

  • 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 asset na resulta ng task.

  • Name
    task_error
    Type
    object
    Description

    Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reperensya 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 FAILED na task (ang mga credit ay ibinabalik 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 na URL para sa animation sa GLB format. Para sa isang task na nilikha gamit ang action_ids, ang nag-iisang file na ito ay naglalaman ng bawat hiniling na aksyon bilang hiwalay na clip.
    • Name
      animation_fbx_url
      Type
      string
      Description
      Downloadable na URL para sa animation sa FBX format. Para sa isang task na nilikha gamit ang action_ids, ang nag-iisang file na ito ay naglalaman ng bawat hiniling na aksyon bilang hiwalay na clip.
    • Name
      processed_usdz_url
      Type
      string
      Description
      Downloadable na URL para sa naiprosesong animation sa USDZ format.
    • Name
      processed_armature_fbx_url
      Type
      string
      Description
      Downloadable na URL para sa naiprosesong armature sa FBX format.
    • Name
      processed_animation_fps_fbx_url
      Type
      string
      Description
      Downloadable na URL para sa animation na may binagong FPS sa FBX format (hal., kung ginamit ang change_fps operation).
  • 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

Ibinabalik ang bawat animation sa library, nakaayos ayon sa action_id. Ang tugon ay kumpletong listahan sa halip na isang page, kaya sapat na ang isang tawag upang mapuno ang isang action picker. Ang mga filter ay nagpapaliit sa resulta; kung hindi ilalagay ang mga ito, makukuha ang lahat.

Para tingnan ang parehong katalogo nang biswal, kasama ang animated preview ng bawat action, tingnan ang Animation Library reference.

Libre ang endpoint na ito — hindi ito gumagamit ng credits.

Mga Parameter

  • Name
    search
    Type
    string
    Description

    Case-insensitive na pagtutugma ng substring sa name o key. Literal na itinutugma, kaya ang % at _ ay karaniwang character lamang at hindi wildcard.

  • Name
    category
    Type
    string
    Description

    Eksaktong pagtutugma sa category.

    Mga magagamit na value:

    • WalkAndRun
    • BodyMovements
    • DailyActions
    • Fighting
    • Dancing
  • Name
    sub_category
    Type
    string
    Description

    Eksaktong pagtutugma sa sub_category. Pwede itong gamitin nang mag-isa — ang mga pangalan ng sub-category ay hindi natatangi sa iba't ibang category (Transitioning ay lumalabas kapwa sa Fighting at DailyActions), kaya kung walang category, itutugma ng filter ang sub-category na iyon saanman ito lumabas.

  • Name
    action_ids
    Type
    string
    Description

    Listahan ng action_id na mga value na pinaghihiwalay ng kuwit na ibabalik, para sa paglutas ng mga partikular na id sa halip na pag-browse. Tumatanggap ng hanggang 200 id. Ang mga id na walang kaukulang animation ay basta na lamang mawawala sa tugon, kaya magagamit mo rin ito upang tingnan kung available pa ang mga id na naka-store sa iyo.

Pagsasama ng mga filter

Ang mga filter ay sabay na inaaplay — bawat isa ay lalo pang nagpapaliit sa resulta, kaya ibabalik lamang ang isang animation kung natutugunan nito ang lahat ng mga ito. Sa loob ng iisang filter, maaaring tumugma ang maraming value sa alinman sa mga ito: ang search ay tumutugma sa name o key, at ang action_ids ay tumutugma sa alinmang id sa listahan.

Nangangahulugan ito na ang kombinasyon na walang pagkakatugma ay magbabalik ng walang-laman na array sa halip na error. Ang action 92 ay "Double Combo Attack", isang Fighting na animation:

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

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

Ibinabalik

Nagbabalik ng listahan ng The Animation Objects.

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

Ang Animation Object

  • Name
    action_id
    Type
    integer
    Description

    Ang value na ipapasa bilang action_id kapag gumagawa ng animation task. Natatangi at matatag, ngunit hindi magkakasunod — ang mga animation na na-retire ay nag-iiwan ng mga puwang sa numbering, kaya huwag kailanman ipagpalagay na valid ang isang hanay ng mga id.

  • Name
    name
    Type
    string
    Description

    Mababasang label para sa tao, para sa pagpapakita. Hindi natatangi: may ilang animation na magkapareho ng pangalan ngunit magkaibang variant, kaya gamitin ang action_id o key bilang identity.

  • Name
    key
    Type
    string
    Description

    Natatangi at matatag na slug para sa animation. Gamitin ito kapag kailangan mo ng non-numeric na identifier bilang key para sa sarili mong storage.

  • Name
    category
    Type
    string
    Description

    Pangkalahatang grouping sa pinakamataas na antas, hal. Fighting.

  • Name
    sub_category
    Type
    string
    Description

    Grouping sa loob ng category, hal. AttackingwithWeapon.

  • Name
    preview_url
    Type
    string
    Description

    URL ng isang animated GIF na nagpapakita ng preview ng aksyon, akma 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"
}