Animation API

Endpoints för att upptäcka tillgängliga animationer och applicera dem på riggade karaktärer.

POST/openapi/v1/animations

Skapa en animationsuppgift

Denna endpoint låter dig skapa en ny uppgift för att applicera en animation på en tidigare riggad karaktär — en förinställd åtgärd från animationsbiblioteket (action_id), flera förinställda åtgärder sammanslagna till en fil (action_ids), eller ett rörelseklipp du genererat med Text to Motion API (motion_task_id). Inkluderar alternativ för efterbearbetning.

Parametrar

Name
rig_task_id
Type
string
Obligatorisk
Description
id för en framgångsrikt slutförd riggningsuppgift (från POST /openapi/v1/rigging). Karaktären från denna uppgift kommer att animeras.
Name
action_id
Type
integer
Description
Identifieraren för den förinställda animationsåtgärden att applicera. Se Animation Library Reference för en fullständig lista över tillgängliga animationer. Ange exakt en av action_id, action_ids eller motion_task_id.
Name
action_ids
Type
array of integers
Description
Flera förinställda animationsåtgärder att applicera samtidigt, returnerade som en enda fil som innehåller ett animationsklipp per åtgärd — användbart för att driva en karaktär från en tillståndsmaskin i en spelmotor. Ange 1 till 10 action_id-värden från Animation Library Reference; id:n måste vara unika. Kostar 3 credits per åtgärd. Ange exakt en av action_id, action_ids eller motion_task_id.
Att skicka en action_ids med ett enda element motsvarar att skicka det värdet som action_id.
Name
motion_task_id
Type
string
Description
id för en framgångsrikt slutförd Text to Motion-uppgift att applicera istället för en förinställd åtgärd. Det genererade klippet återmålas (retargetas) på den riggade karaktären och klippet ögonblicksbildas vid skapandetillfället, så denna uppgift påverkas inte om källuppgiften senare upphör att gälla eller raderas. Källuppgiftens tillgångar sparas i 3 dagar — applicera klippet innan det upphör att gälla. Kräver en tvåbent rigg. Ange exakt en av action_id, action_ids eller motion_task_id.
Name
post_process
Type
object
Description
Valfri efterbearbetning för animationsutdatan. Utelämna den för att få standardanimationsfilerna.

Gäller endast när post_process is set

Name
operation_type
Type
string
Obligatorisk
Description
Typen av åtgärd att utföra. Tillgängliga värden: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
standard 30
Description
Målbildfrekvensen. Gäller endast när operation_type är change_fps. Tillåtna värden: 24, 25, 30, 60.

Med action_ids returnerar uppgiften en sammanslagen fil istället för en fil per åtgärd: animation_glb_url och animation_fbx_url pekar båda på en enda tillgång som innehåller varje begärd åtgärd som ett separat klipp.

Klippordning: ordningen i arrayen action_ids, inte den numeriska ordningen på id:na.
Klippnamn: animationens namn i biblioteket, matchande de namn du får när du exporterar alla animationer för en karaktär som en enda fil från Meshy-webbappen. Om två begärda id:n resulterar i samma klippnamn får det senare ett suffix med sitt action_id för att hålla namnen unika.
Efterbearbetning: appliceras på den sammanslagna filen, inte på de enskilda klippen.

Med motion_task_id kan återmålningen (retargeten) resultera i en animation som endast finns som GLB. Om du begärde post_process och ingen FBX är tillgänglig misslyckas uppgiften med ett task_error och dina credits återbetalas automatiskt; utan post_process lyckas uppgiften och animation_fbx_url är tom.

Returer

Egenskapen result i svaret innehåller uppgifts-id för den nyskapade animationsuppgiften.

Felfall

Name
400 - Bad Request
Description
Begäran kunde inte accepteras. Vanliga orsaker:
- Saknad parameter: rig_task_id saknas, eller ingen av action_id, action_ids och motion_task_id har angetts.
- Motstridiga parametrar: mer än en av action_id, action_ids och motion_task_id angavs — de är ömsesidigt uteslutande.
- Ogiltig riggningsuppgift: rig_task_id är ogiltig eller refererar till en misslyckad/icke-existerande uppgift.
- Ogiltigt action-ID: ett action_id — eller en post i action_ids — motsvarar inte en giltig animation.
- För många åtgärder: action_ids innehåller fler än 10 id:n.
- Duplicerade åtgärder: action_ids innehåller samma id mer än en gång.
- Rörelseuppgift inte redo: uppgiften för motion_task_id har ännu inte fått status SUCCEEDED.
- Rigg saknar stöd: motion_task_id kräver en tvåbent rigg; fyrbenta riggar avvisas.
Name
401 - Unauthorized
Description
Autentiseringen misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med credits för att utföra denna uppgift.
Name
404 - Not Found
Description
Riggningsuppgiften som anges av rig_task_id hittades inte, rörelseuppgiften som anges av motion_task_id hittades inte, eller rörelseklippet har upphört att gälla (källuppgiftens tillgångar sparas i 3 dagar).
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

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

Hämta en Animation-uppgift

Denna endpoint låter dig hämta en Animation-uppgift givet ett giltigt uppgifts-id. Se The Animation Task Object för att se vilka egenskaper som ingår.

Parametrar

Name
id
Type
path
Description
Unik identifierare för den Animation-uppgift som ska hämtas.

Returer

Svaret innehåller Animation Task-objektet. Se avsnittet The Animation Task Object för detaljer.

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

Ta bort en Animation-uppgift

Denna endpoint tar permanent bort en Animation-uppgift, inklusive alla tillhörande modeller och data. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för den Animation-uppgift som ska tas bort.

Uppgiftsstatus

En uppgift som fortfarande är PENDING tas bort och de credits som förbrukades vid skapandet återbetalas.

En uppgift som redan är IN_PROGRESS kan inte tas bort: förfrågan avvisas med 409 Conflict och uppgiften fortsätter att köras. Credits för en uppgift som arbetaren redan har påbörjat kan inte återbetalas, så att ta bort den mitt i körningen skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, ta sedan bort den.

En uppgift i ett sluttillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort utan återbetalning.

Returer

Returnerar 200 OK vid framgång, eller 409 Conflict när uppgiften är 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

Lista animationsuppgifter

Returnerar en paginerad lista över den anropande partens animationsuppgifter, nyaste först. Standardpaginering via page_num och page_size.

Observera att uppgifter som skapats via API:et hanteras via API:et — de visas inte i webbappens Mina tillgångar. Använd denna endpoint för att hitta en uppgift vars ID du inte längre har.

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

Streama en Animation-uppgift

Denna endpoint strömmar realtidsuppdateringar för en Animation-uppgift med hjälp av Server-Sent Events (SSE).

Parametrar

Name
id
Type
path
Description
Unik identifierare för den Animation-uppgift som ska strömmas.

Returer

Returnerar en ström av The Animation Task Objects som Server-Sent Events.

För uppgifter med status PENDING eller IN_PROGRESS kommer svarsströmmen endast att innehålla nödvändiga fält för progress och 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
}

Animation-uppgiftsobjektet

Animation-uppgiftsobjektet representerar arbetsenheten för att tillämpa en animation på en riggad karaktär.

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften.
Name
type
Type
string
Description
Typ av Animation-uppgift. Värdet är animate.
Name
status
Type
string
Description
Status för uppgiften. Möjliga värden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress för uppgiften (0-100).
Name
created_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiften skapades.
En tidsstämpel representerar antalet millisekunder som förflutit sedan 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredag 1 september 2023 kl. 12:00:00 GMT som 1693569600000. Detta gäller för alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiften började bearbetas. 0 om den inte har startat.
Name
finished_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiften avslutades. 0 om den inte är avslutad.
Name
expires_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiftens resultat-assets går ut.
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter. Se Fel för den fullständiga referensen för task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Finns när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).
Name
result
Type
object
Description
Innehåller URL:er till de resulterande animationsfilerna om uppgiften SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för animationen i GLB-format. För en uppgift skapad med action_ids innehåller denna enda fil varje begärd action som ett separat klipp.
- Name
  animation_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för animationen i FBX-format. För en uppgift skapad med action_ids innehåller denna enda fil varje begärd action som ett separat klipp.
- Name
  processed_usdz_url
  Type
  string
  Description
  Nedladdningsbar URL för den bearbetade animationen i USDZ-format.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för den bearbetade armaturen i FBX-format.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för animationen med ändrad FPS i FBX-format (t.ex. om operationen change_fps användes).
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter i kön. Endast relevant om status är 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

Lista animationer

Returnerar alla animationer i biblioteket, sorterade efter action_id. Svaret är en komplett lista snarare än en sida, så ett enda anrop räcker för att fylla en åtgärdsväljare. Filter begränsar resultatet; utelämna dem alla för att hämta allt.

För att bläddra i samma katalog visuellt, med en animerad förhandsgranskning av varje åtgärd, se Animationsbibliotek-referensen.

Denna endpoint är gratis — den förbrukar inga credits.

Parametrar

Name
search
Type
string
Description
Skiftlägesokänslig delsträngsmatchning på name eller key. Matchas bokstavligt, så % och _ är vanliga tecken snarare än jokertecken.
Name
category
Type
string
Description
Exakt matchning på category.
Tillgängliga värden:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Exakt matchning på sub_category. Accepteras fristående — underkategorinamn är inte unika mellan kategorier (Transitioning förekommer under både Fighting och DailyActions), så utan en category matchar filtret den underkategorin var den än förekommer.
Name
action_ids
Type
string
Description
Kommaseparerad lista med action_id-värden att returnera, för att slå upp specifika id:n snarare än att bläddra. Accepterar högst 200 id:n. Id:n som ingen animation har saknas helt enkelt i svaret, så du kan även använda detta för att kontrollera om id:n du har lagrat fortfarande är tillgängliga.

Kombinera filter

Filter tillämpas tillsammans — varje filter begränsar resultatet ytterligare, så en animation returneras endast om den uppfyller alla. Inom ett enskilt filter matchar flera värden mot vilket som helst av dem: search matchar name eller key, och action_ids matchar vilket id som helst i listan.

Det betyder att en kombination utan överlappning returnerar en tom array snarare än ett fel. Åtgärd 92 är "Double Combo Attack", en Fighting-animation:

?action_ids=92&category=Fighting returnerar åtgärd 92.
?action_ids=92&category=Dancing returnerar [] — den är inte en Dancing-animation.
?action_ids=92&search=walk returnerar [] — dess namn matchar inte walk.

För att hämta specifika animationer oavsett deras kategori, ange action_ids fristående.

Returer

Returnerar en lista med Animationsobjekten.

Varje action_id som returneras här accepteras av Skapa en animationsuppgift ovan, och varje id som den accepterar returneras här. Utfasade animationer saknas i båda. Om du cachar biblioteket, uppdatera det regelbundet så att ett utfasat id inte blir kvar i din väljare.

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

Animation-objektet

Name
action_id
Type
integer
Description
Värdet som ska anges som action_id när en animationsuppgift skapas. Unikt och stabilt, men inte sammanhängande — animationer som tas ur bruk lämnar luckor i numreringen, så anta aldrig att ett intervall av id:n är giltigt.
Name
name
Type
string
Description
Läsbar etikett, för visning. Inte unik: vissa animationer delar namn med en annan variant, så använd action_id eller key som identitet.
Name
key
Type
string
Description
Unik och stabil slug för animationen. Använd den när du behöver en icke-numerisk identifierare att basera din egen lagring på.
Name
category
Type
string
Description
Övergripande gruppering, t.ex. Fighting.
Name
sub_category
Type
string
Description
Gruppering inom kategorin, t.ex. AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL till en animerad GIF som förhandsvisar handlingen, lämplig att rendera direkt i din egen väljare.

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