API pro animace

Endpointy pro vyhledávání dostupných animací a jejich aplikaci na postavy s riggem.

POST/openapi/v1/animations

Vytvoření úlohy animace

Tento koncový bod umožňuje vytvořit novou úlohu pro aplikaci animace na dříve rigovanou postavu — přednastavenou akci z knihovny animací (action_id), několik přednastavených akcí sloučených do jednoho souboru (action_ids), nebo klip pohybu vygenerovaný pomocí Text to Motion API (motion_task_id). Zahrnuje možnosti následného zpracování.

Parametry

Name
rig_task_id
Type
string
Povinné
Description
id úspěšně dokončené úlohy riggingu (z POST /openapi/v1/rigging). Postava z této úlohy bude animována.
Name
action_id
Type
integer
Description
Identifikátor přednastavené animační akce, která se má použít. Kompletní seznam dostupných animací najdete v referenci Knihovny animací. Zadejte přesně jeden z parametrů action_id, action_ids nebo motion_task_id.
Name
action_ids
Type
array of integers
Description
Několik přednastavených animačních akcí, které se mají použít najednou, vrácených jako jeden soubor obsahující jeden animační klip na akci — užitečné pro řízení postavy pomocí stavového automatu v herním enginu. Zadejte 1 až 10 hodnot action_id z reference Knihovny animací; ID musí být jedinečná. Stojí 3 kredity za akci. Zadejte přesně jeden z parametrů action_id, action_ids nebo motion_task_id.
Předání action_ids s jedním prvkem je ekvivalentní předání této hodnoty jako action_id.
Name
motion_task_id
Type
string
Description
id úspěšně dokončené úlohy Text to Motion, která se má použít místo přednastavené akce. Vygenerovaný klip je přemapován na rigovanou postavu a klip je zachycen v okamžiku vytvoření, takže tato úloha není ovlivněna, pokud zdrojová úloha později expiruje nebo je smazána. Assety zdrojové úlohy jsou uchovávány po dobu 3 dnů — použijte klip před jeho expirací. Vyžaduje dvounohý rig. Zadejte přesně jeden z parametrů action_id, action_ids nebo motion_task_id.
Name
post_process
Type
object
Description
Volitelné následné zpracování výstupu animace. Vynechte jej, chcete-li obdržet standardní soubory animace.

Platí pouze když post_process is set

Name
operation_type
Type
string
Povinné
Description
Typ operace, která se má provést. Dostupné hodnoty: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
výchozí 30
Description
Cílová snímková frekvence. Platí pouze v případě, že operation_type je change_fps. Povolené hodnoty: 24, 25, 30, 60.

S parametrem action_ids vrací úloha jeden sloučený soubor namísto jednoho souboru na akci: animation_glb_url a animation_fbx_url odkazují na jediný asset obsahující každou požadovanou akci jako samostatný klip.

Pořadí klipů: pořadí pole action_ids, nikoli číselné pořadí ID.
Názvy klipů: název animace v knihovně, odpovídající názvům, které získáte při exportu všech animací postavy jako jednoho souboru z webové aplikace Meshy. Pokud dvě požadovaná ID odpovídají stejnému názvu klipu, pozdější z nich má k názvu přidán jeho action_id, aby byly názvy jedinečné.
Následné zpracování: aplikováno na sloučený soubor, nikoli na jednotlivé klipy.

S parametrem motion_task_id může přemapování vytvořit animaci pouze ve formátu GLB. Pokud jste požadovali post_process a FBX není k dispozici, úloha selže s chybou task_error a vaše kredity budou automaticky vráceny; bez post_process úloha uspěje a animation_fbx_url je prázdné.

Návratové hodnoty

Vlastnost result v odpovědi obsahuje id úlohy nově vytvořené animační úlohy.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Časté příčiny:
- Chybějící parametr: chybí rig_task_id, nebo není zadán žádný z parametrů action_id, action_ids a motion_task_id.
- Konfliktní parametry: bylo zadáno více než jedno z action_id, action_ids a motion_task_id — tyto parametry se vzájemně vylučují.
- Neplatná úloha riggingu: rig_task_id je neplatné nebo odkazuje na neúspěšnou/neexistující úlohu.
- Neplatné ID akce: action_id — nebo položka z action_ids — neodpovídá platné animaci.
- Příliš mnoho akcí: action_ids obsahuje více než 10 ID.
- Duplicitní akce: action_ids obsahuje stejné ID vícekrát.
- Úloha pohybu není připravena: úloha motion_task_id ještě nedosáhla stavu SUCCEEDED.
- Nepodporovaný rig: motion_task_id vyžaduje dvounohý rig; čtyřnohé rigy jsou odmítnuty.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení této úlohy.
Name
404 - Not Found
Description
Úloha riggingu specifikovaná pomocí rig_task_id nebyla nalezena, úloha pohybu specifikovaná pomocí motion_task_id nebyla nalezena, nebo klip pohybu vypršel (assety zdrojové úlohy jsou uchovávány po dobu 3 dnů).
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti.

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

Retrieve an Animation Task

Tento koncový bod umožňuje načíst úlohu animace na základě platného id úlohy. Podrobnosti o vlastnostech, které jsou zahrnuty, naleznete v The Animation Task Object.

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy animace, kterou chcete načíst.

Návratová hodnota

Odpověď obsahuje objekt Animation Task. Podrobnosti naleznete v sekci The Animation Task Object.

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

Tento koncový bod trvale odstraní úlohu animace, včetně všech souvisejících modelů a dat. Tuto akci nelze vrátit zpět.

Parametry cesty

Name
id
Type
path
Description
ID úlohy animace, kterou chcete odstranit.

Stav úlohy

Úloha, která je stále ve stavu PENDING, je odstraněna a kredity spotřebované při jejím vytvoření jsou vráceny.

Úlohu, která je již ve stavu IN_PROGRESS, nelze odstranit: požadavek je odmítnut s 409 Conflict a úloha pokračuje v běhu. Kredity za úlohu, kterou už worker začal zpracovávat, nejsou vratné, takže odstranění během běhu by vás stálo kredity i výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji odstraňte.

Úloha v koncovém stavu (SUCCEEDED, FAILED nebo CANCELED) je odstraněna bez vrácení kreditů.

Návratové hodnoty

Při úspěchu vrací 200 OK, nebo 409 Conflict, pokud je úloha ve stavu 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

Seznam úkolů animace

Vrací stránkovaný seznam úkolů animace volajícího, seřazený od nejnovějších. Standardní stránkování pomocí page_num a page_size.

Upozorňujeme, že úkoly vytvořené přes API jsou spravovány přes API — nezobrazují se v sekci Moje assety ve webové aplikaci. Tento koncový bod použijte k vyhledání úkolu, jehož ID již nemáte.

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

Streamování úlohy animace

Tento koncový bod streamuje aktualizace v reálném čase pro úlohu Animace pomocí Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Animace, kterou chcete streamovat.

Návratová hodnota

Vrací proud Objektů úlohy animace formou Server-Sent Events.

U úloh se stavem PENDING nebo IN_PROGRESS bude datový proud odpovědi obsahovat pouze nezbytná pole progress a 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
}

Objekt úlohy Animace

Objekt úlohy Animace představuje pracovní jednotku pro aplikování animace na postavu s riggem.

Vlastnosti

Name
id
Type
string
Description
Jedinečný identifikátor úlohy.
Name
type
Type
string
Description
Typ úlohy Animace. Hodnota je animate.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress úlohy (0-100).
Name
created_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy), kdy byla úloha vytvořena.
Časové razítko představuje počet milisekund uplynulých od 1. ledna 1970 UTC podle standardu RFC 3339. Například pátek 1. září 2023 12:00:00 GMT je reprezentován jako 1693569600000. Toto platí pro všechna časová razítka v Meshy API.
Name
started_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy), kdy úloha začala zpracování. 0, pokud nebyla zahájena.
Name
finished_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy), kdy úloha skončila. 0, pokud ještě neskončila.
Name
expires_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy), kdy vyprší platnost výstupních assetů úlohy.
Name
task_error
Type
object
Description
Podrobnosti chyby pro neúspěšné úlohy. Úplnou referenci objektu task_error najdete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomno, pokud je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. U úloh se stavem FAILED vrací 0 (při selhání jsou kredity vráceny).
Name
result
Type
object
Description
Obsahuje URL adresy výstupní animace, pokud úloha skončila se stavem SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL ke stažení animace ve formátu GLB. U úlohy vytvořené s action_ids obsahuje tento jediný soubor každou požadovanou akci jako samostatný klip.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL ke stažení animace ve formátu FBX. U úlohy vytvořené s action_ids obsahuje tento jediný soubor každou požadovanou akci jako samostatný klip.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL ke stažení zpracované animace ve formátu USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL ke stažení zpracované armatury ve formátu FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL ke stažení animace se změněnou snímkovou frekvencí (FPS) ve formátu FBX (např. pokud byla použita operace change_fps).
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh ve frontě. Má smysl pouze v případě, že stav je 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

Seznam animací

Vrací všechny animace v knihovně, seřazené podle action_id. Odpověď je kompletní seznam, nikoli stránka, takže k naplnění výběru akcí stačí jedno volání. Filtry výsledek zužují; pokud je všechny vynecháte, získáte úplně vše.

Chcete-li si stejný katalog prohlédnout očima, s animovaným náhledem každé akce, podívejte se na referenci Knihovny animací.

Tento koncový bod je zdarma — nespotřebovává žádné kredity.

Parametry

Name
search
Type
string
Description
Shoda podřetězce v name nebo key, nerozlišující velikost písmen. Porovnává se doslovně, takže % a _ jsou běžné znaky, nikoli zástupné symboly.
Name
category
Type
string
Description
Přesná shoda na category.
Dostupné hodnoty:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Přesná shoda na sub_category. Lze použít samostatně — názvy podkategorií nejsou napříč kategoriemi jedinečné (Transitioning se objevuje jak pod Fighting, tak pod DailyActions), takže bez category filtr odpovídá dané podkategorii kdekoli se vyskytuje.
Name
action_ids
Type
string
Description
Seznam hodnot action_id oddělených čárkou, které se mají vrátit, pro zjišťování konkrétních id namísto procházení. Přijímá nejvýše 200 id. Id, která nemá žádná animace, se v odpovědi jednoduše nevyskytují, takže to lze také použít ke kontrole, zda jsou id, která máte uložená, stále dostupná.

Kombinování filtrů

Filtry se uplatňují společně — každý z nich výsledek dále zužuje, takže animace je vrácena pouze tehdy, splňuje-li všechny z nich. V rámci jednoho filtru odpovídá libovolná z více hodnot: search odpovídá name nebo key a action_ids odpovídá libovolnému id v seznamu.

To znamená, že kombinace bez průniku vrátí prázdné pole místo chyby. Akce 92 je „Double Combo Attack“, animace typu Fighting:

?action_ids=92&category=Fighting vrátí akci 92.
?action_ids=92&category=Dancing vrátí [] — nejde o animaci typu Dancing.
?action_ids=92&search=walk vrátí [] — její název neodpovídá walk.

Chcete-li získat konkrétní animace bez ohledu na jejich kategorii, předejte action_ids samostatně.

Návratová hodnota

Vrací seznam objektů Animation.

Každé action_id vrácené zde je přijímáno metodou Vytvořit úlohu animace výše a každé id, které přijímá, je vráceno zde. Zrušené animace chybí v obou. Pokud si knihovnu ukládáte do mezipaměti, pravidelně ji obnovujte, aby se zrušené id v jejím výběru dlouho neudrželo.

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

Objekt Animace

Name
action_id
Type
integer
Description
Hodnota, kterou je třeba předat jako action_id při vytváření úlohy animace. Unikátní a stabilní, ale ne souvislá — zrušené animace zanechávají v číslování mezery, takže nikdy nepředpokládejte, že je platný celý rozsah id.
Name
name
Type
string
Description
Popisek čitelný pro člověka, určený k zobrazení. Není jedinečný: některé animace sdílejí název s jinou variantou, proto jako identitu použijte action_id nebo key.
Name
key
Type
string
Description
Jedinečný a stabilní slug pro animaci. Použijte jej, když potřebujete nečíselný identifikátor, podle kterého budete indexovat vlastní úložiště.
Name
category
Type
string
Description
Nejvyšší úroveň seskupení, např. Fighting.
Name
sub_category
Type
string
Description
Seskupení v rámci kategorie, např. AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL animovaného GIFu s náhledem akce, vhodné pro přímé zobrazení ve vlastním výběrovém nástroji.

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