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.
Gamit ang action_ids, ibinabalik ng gawain ang isang pinagsamang file sa halip na isang file kada action: ang animation_glb_url at animation_fbx_url ay bawat isa ay tumuturo sa iisang asset na naglalaman ng bawat hiniling na action bilang hiwalay na clip.
Pagkakasunod-sunod ng clip: ang pagkakasunod-sunod ng array na action_ids, hindi ang numerikong pagkakasunod-sunod ng mga id.
Mga pangalan ng clip: ang pangalan ng animation sa library, na tumutugma sa mga pangalan na makukuha mo kapag ini-export ang lahat ng animation ng isang karakter bilang iisang file mula sa Meshy web app. Kung ang dalawang hiniling na id ay nagreresulta sa parehong pangalan ng clip, ang huling isa ay bibigyan ng suffix na kanyang action_id upang mapanatiling natatangi ang mga pangalan.
Post-processing: inilalapat sa pinagsamang file, hindi sa mga indibidwal na clip.
Gamit ang motion_task_id, maaaring makagawa ang retarget ng isang animation na GLB lamang. Kung hiniling mo ang post_process at walang available na FBX, mabibigo ang gawain na may task_error at awtomatikong ire-refund ang iyong mga credits; kung walang post_process, magtatagumpay ang gawain at ang animation_fbx_url ay magiging walang laman.
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 onlycurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 FPScurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 } }'
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.
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.
// 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."}
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.
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.
Ang isang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, kasunod ng
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 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.
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.
Bawat action_id na ibinabalik dito ay tinatanggap ng Create an Animation Task sa itaas, at bawat id na tinatanggap nito ay ibinabalik dito. Ang mga retirado nang animation ay wala sa pareho. Kung i-cache mo ang library, i-refresh ito paminsan-minsan upang hindi magpatuloy ang isang retirado nang id sa iyong picker.
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.