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 rörelse från animationsbiblioteket (action_id), flera förinställda rörelser sammanslagna till en fil (action_ids), eller en rörelseklipp du genererat med Text to Motion API (motion_task_id). Inkluderar alternativ för efterbearbetning.

Uppgiften körs i bakgrunden. För information om hur lång tid det vanligtvis tar, se Bearbetningstider.

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 animationsrörelse som ska appliceras. Se referensen för Animationsbiblioteket 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 animationsrörelser att applicera på en gång, returnerade som en enda fil som innehåller ett animationsklipp per rörelse — 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 referensen för Animationsbiblioteket; id:n måste vara unika. Kostar 3 credits per rörelse. 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 rörelse. Det genererade klippet retargetas till den riggade karaktären och klippet ögonblicksavbildas vid skapandet, så denna uppgift påverkas inte om källuppgiften senare upphör att gälla eller tas bort. Källuppgiftens tillgångar behålls 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 animationsresultatet. Utelämna den för att få de vanliga animationsfilerna.

Gäller endast när post_process is set

Name
operation_type
Type
string
Obligatorisk
Description
Typen av åtgärd som ska utföras. 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 enda sammanslagen fil istället för en fil per rörelse: animation_glb_url och animation_fbx_url pekar var och en på en enda tillgång som innehåller varje begärd rörelse som ett separat klipp.

Klippordning: ordningen i arrayen action_ids, inte den numeriska ordningen av id:na.
Klippnamn: animationens namn i biblioteket, som matchar namnen 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 den senare ett suffix med sitt action_id för att hålla namnen unika.
Efterbearbetning: tillämpas på den sammanslagna filen, inte på de enskilda klippen.

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

Returnerar

Svarets result-egenskap innehåller id för den nyskapade animationsuppgiften.

Felscenarier

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 utesluter varandra ömsesidigt.
- Ogiltig riggningsuppgift: rig_task_id är ogiltig eller refererar till en misslyckad/obefintlig uppgift.
- Ogiltigt rörelse-ID: Ett action_id — eller en post i action_ids — motsvarar inte en giltig animation.
- För många rörelser: action_ids innehåller fler än 10 id:n.
- Duplicerade rörelser: action_ids innehåller samma id mer än en gång.
- Rörelseuppgift inte klar: motion_task_id-uppgiften har ännu inte SUCCEEDED.
- Rigg stöds inte: 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 behålls 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 animationsuppgift

Denna endpoint låter dig hämta en animationsuppgift 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 animationsuppgiften som ska hämtas.

Returnerar

Svaret innehåller Animation-uppgiftsobjektet. 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 animationsuppgift

Denna endpoint tar permanent bort en animationsuppgift, inklusive alla tillhörande modeller och data. Denna åtgärd kan inte ångras.

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för den animationsuppgift 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 resultat. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

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

Returnerar

Returnerar 200 OK vid lyckad borttagning, 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

List Animation Tasks

Returnerar en paginerad lista över anroparens animation-tasks, nyaste först. Standardpaginering via page_num och page_size.

Observera att tasks som skapats via API:t hanteras via API:t — de visas inte i webbappens My Assets. Använd denna endpoint för att hitta en task 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

Strömma en Animation-uppgift

Denna endpoint strömmar uppdateringar i realtid 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.

Returnerar

Returnerar en ström av Animation-uppgiftsobjekt som Server-Sent Events.

För uppgifter med status PENDING eller IN_PROGRESS kommer svarsströmmen endast att innehålla de nödvändiga fälten 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 applicera 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-uppgiften. 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 den 1 januari 1970 UTC, i enlighet med standarden RFC 3339. Till exempel representeras fredagen den 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 upphör att gälla.
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 genererade animationerna 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. Har endast betydelse 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 varje animation 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 referensen för Animationsbibliotek.

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 på egen hand — namn på underkategorier är inte unika mellan kategorier (Transitioning förekommer under både Fighting och DailyActions), så utan en category matchar filtret den underkategorin varhelst den 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 som mest 200 id:n. Id:n som ingen animation har saknas helt enkelt i svaret, så du kan också använda detta för att kontrollera om id:n du har sparat fortfarande är tillgängliga.

Kombinera filter

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

Det innebär 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 kategori, ange action_ids på egen hand.

Returvärden

Returnerar en lista med Animationsobjekt.

Varje action_id som returneras här accepteras av Skapa en animationsuppgift ovan, och varje id den accepterar returneras här. Utgångna animationer saknas i båda. Om du cachar biblioteket, uppdatera det regelbundet så att ett utgånget 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 skickas som action_id vid skapandet av en animationsuppgift. Unikt och stabilt, men inte sammanhängande — animationer som tagits bort 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, 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 rörelsen, lämplig att visa 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"
}