Animace API

Endpointy pro zjišťování dostupných animací a jejich aplikaci na postavy s kostrou.

POST/openapi/v1/animations

Vytvoření úkolu animace

Tento koncový bod umožňuje vytvořit nový úkol pro aplikaci animace na dříve rigovanou postavu — buď přednastavenou akci z knihovny animací (action_id), nebo pohybovou sekvenci vygenerovanou 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ého úkolu rigování (z POST /openapi/v1/rigging). Postava z tohoto úkolu bude animována.
Name
action_id
Type
integer
Description
Identifikátor přednastavené animační akce, která se má použít. Úplný seznam dostupných animací naleznete v referenci Knihovny animací. Zadejte přesně jeden z parametrů action_id nebo motion_task_id.
Name
motion_task_id
Type
string
Description
id úspěšně dokončeného úkolu Text to Motion, který se má použít místo přednastavené akce. Vygenerovaná sekvence je přemapována na rigovanou postavu a sekvence je zachycena v čase vytvoření, takže tento úkol není ovlivněn, pokud zdrojový úkol později vyprší nebo je smazán. Assety zdrojového úkolu jsou uchovávány po dobu 3 dnů — použijte sekvenci před jejím vypršením. Vyžaduje dvounohý rig. Zadejte přesně jeden z parametrů action_id nebo motion_task_id.
Name
post_process
Type
object
Description
Volitelné následné zpracování výstupu animace. Pokud jej vynecháte, obdržíte standardní animační soubory.

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 motion_task_id může přemapování vytvořit animaci pouze ve formátu GLB. Pokud jste požádali o post_process a soubor FBX není k dispozici, úkol selže s chybou task_error a vaše kredity jsou automaticky vráceny; bez post_process úkol uspěje a animation_fbx_url je prázdné.

Návratová hodnota

Vlastnost result v odpovědi obsahuje id úkolu nově vytvořeného úkolu animace.

Chybové stavy

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Běžné příčiny:
- Chybějící parametr: chybí rig_task_id, nebo není zadán ani action_id, ani motion_task_id.
- Konfliktní parametry: byly zadány jak action_id, tak motion_task_id — jsou vzájemně se vylučující.
- Neplatný úkol rigování: rig_task_id je neplatný nebo odkazuje na neúspěšný/neexistující úkol.
- Neplatné ID akce: action_id neodpovídá platné animaci.
- Úkol pohybu není připraven: úkol motion_task_id ještě nemá stav SUCCEEDED.
- Nepodporovaný rig: motion_task_id vyžaduje dvounohý rig; čtyřnohé rigy jsou odmítnuty.
Name
401 - Unauthorized
Description
Autentizace se nezdařila. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení tohoto úkolu.
Name
404 - Not Found
Description
Úkol rigování určený parametrem rig_task_id nebyl nalezen, úkol pohybu určený parametrem motion_task_id nebyl nalezen, nebo platnost pohybové sekvence vypršela (assety zdrojového úkolu jsou uchovávány po dobu 3 dnů).
Name
429 - Too Many Requests
Description
Překročili jste svůj 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 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

Odstranit úlohu Animace

Tento koncový bod trvale odstraní úlohu Animace, včetně všech souvisejících modelů a dat. Tato akce je nevratná.

Parametry cesty

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

Návratová hodnota

V případě úspěchu vrací 200 OK.

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

// Returns 200 Ok on success.

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 animačního úkolu

Objekt animačního úkolu představuje jednotku práce pro aplikaci animace na postavu s vytvořeným rigem.

Vlastnosti

Name
id
Type
string
Description
Jedinečný identifikátor úkolu.
Name
type
Type
string
Description
Typ animačního úkolu. Hodnota je animate.
Name
status
Type
string
Description
Stav úkolu. Možné hodnoty: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress úkolu (0–100).
Name
created_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) udávající, kdy byl úkol vytvořen.
Č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. To platí pro všechna časová razítka v Meshy API.
Name
started_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) udávající, kdy úkol začal zpracování. 0, pokud nebyl zahájen.
Name
finished_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) udávající, kdy byl úkol dokončen. 0, pokud nebyl dokončen.
Name
expires_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) udávající, kdy vyprší platnost výsledných assetů úkolu.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úkolů. Kompletní referenci objektu task_error najdete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných tímto úkolem. Je přítomno, pokud je stav úkolu PENDING, IN_PROGRESS nebo SUCCEEDED. U úkolů se stavem FAILED vrací 0 (kredity jsou při selhání vráceny).
Name
result
Type
object
Description
Obsahuje URL adresy výstupní animace, pokud úkol skončil se stavem SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL ke stažení animace ve formátu GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL ke stažení animace ve formátu FBX.
- 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 hodnotou 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 úkolů ve frontě. Má význam 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
}