API Animacji

Endpointy służące do odkrywania dostępnych Animacji i stosowania ich do postaci posiadających rig.

POST/openapi/v1/animations

Utwórz zadanie animacji

Ten punkt końcowy pozwala utworzyć nowe zadanie polegające na zastosowaniu animacji do wcześniej zriggowanej postaci — gotowej akcji z biblioteki animacji (action_id), kilku gotowych akcji połączonych w jeden plik (action_ids) lub klipu ruchu wygenerowanego za pomocą Text to Motion API (motion_task_id). Zawiera opcje przetwarzania końcowego.

Parametry

Name
rig_task_id
Type
string
Wymagane
Description
id pomyślnie zakończonego zadania riggingu (z POST /openapi/v1/rigging). Postać z tego zadania zostanie zanimowana.
Name
action_id
Type
integer
Description
Identyfikator gotowej akcji animacji do zastosowania. Pełną listę dostępnych animacji znajdziesz w Animation Library Reference. Podaj dokładnie jedną wartość spośród action_id, action_ids lub motion_task_id.
Name
action_ids
Type
array of integers
Description
Kilka gotowych akcji animacji do zastosowania jednocześnie, zwracanych jako pojedynczy plik zawierający jeden klip animacji na akcję — przydatne do sterowania postacią z poziomu maszyny stanów w silniku gry. Podaj od 1 do 10 wartości action_id z Animation Library Reference; identyfikatory muszą być unikalne. Koszt to 3 kredyty za akcję. Podaj dokładnie jedną wartość spośród action_id, action_ids lub motion_task_id.
Przekazanie action_ids z jednym elementem jest równoważne przekazaniu tej wartości jako action_id.
Name
motion_task_id
Type
string
Description
id pomyślnie zakończonego zadania Text to Motion, które ma zostać zastosowane zamiast gotowej akcji. Wygenerowany klip jest przenoszony (retargeted) na zriggowaną postać, a jego stan jest zapisywany w momencie utworzenia zadania, dzięki czemu to zadanie nie jest naruszane, jeśli zadanie źródłowe później wygaśnie lub zostanie usunięte. Zasoby zadania źródłowego są przechowywane przez 3 dni — zastosuj klip, zanim wygaśnie. Wymaga rigu dwunożnego. Podaj dokładnie jedną wartość spośród action_id, action_ids lub motion_task_id.
Name
post_process
Type
object
Description
Opcjonalne przetwarzanie końcowe dla wyniku animacji. Pomiń ten parametr, aby otrzymać standardowe pliki animacji.

Dotyczy tylko gdy post_process is set

Name
operation_type
Type
string
Wymagane
Description
Rodzaj operacji do wykonania. Dostępne wartości: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
domyślne 30
Description
Docelowa liczba klatek na sekundę. Ma zastosowanie tylko wtedy, gdy operation_type to change_fps. Dozwolone wartości: 24, 25, 30, 60.

W przypadku action_ids zadanie zwraca jeden połączony plik zamiast jednego pliku na akcję: animation_glb_url oraz animation_fbx_url wskazują na pojedynczy zasób zawierający każdą żądaną akcję jako osobny klip.

Kolejność klipów: zgodna z kolejnością tablicy action_ids, a nie z liczbowym porządkiem identyfikatorów.
Nazwy klipów: nazwa animacji w bibliotece, zgodna z nazwami otrzymywanymi przy eksporcie wszystkich animacji postaci jako jednego pliku z aplikacji webowej Meshy. Jeśli dwa żądane identyfikatory odpowiadają tej samej nazwie klipu, do nazwy późniejszego dodawany jest sufiks z jego action_id, aby zachować unikalność nazw.
Przetwarzanie końcowe: stosowane do połączonego pliku, a nie do poszczególnych klipów.

W przypadku motion_task_id retargeting może dać animację dostępną wyłącznie w formacie GLB. Jeśli zażądano post_process, a plik FBX nie jest dostępny, zadanie kończy się niepowodzeniem z błędem task_error, a Twoje kredyty są automatycznie zwracane; bez post_process zadanie kończy się sukcesem, a animation_fbx_url jest puste.

Zwracane dane

Właściwość result odpowiedzi zawiera id zadania nowo utworzonego zadania animacji.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie było niepoprawne. Typowe przyczyny:
- Brakujący parametr: brak rig_task_id lub nie podano żadnego z action_id, action_ids i motion_task_id.
- Konfliktujące parametry: podano więcej niż jeden z action_id, action_ids i motion_task_id — wzajemnie się one wykluczają.
- Nieprawidłowe zadanie riggingu: rig_task_id jest nieprawidłowe lub odnosi się do nieudanego/nieistniejącego zadania.
- Nieprawidłowy identyfikator akcji: action_id — lub element action_ids — nie odpowiada żadnej prawidłowej animacji.
- Zbyt wiele akcji: action_ids zawiera więcej niż 10 identyfikatorów.
- Zduplikowane akcje: action_ids zawiera ten sam identyfikator więcej niż raz.
- Zadanie ruchu nie jest gotowe: zadanie motion_task_id jeszcze nie osiągnęło stanu SUCCEEDED.
- Nieobsługiwany rig: motion_task_id wymaga rigu dwunożnego; rigi czworonożne są odrzucane.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
404 - Not Found
Description
Nie znaleziono zadania riggingu wskazanego przez rig_task_id, nie znaleziono zadania ruchu wskazanego przez motion_task_id, lub klip ruchu wygasł (zasoby zadania źródłowego są przechowywane przez 3 dni).
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości.

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

Ten punkt końcowy umożliwia pobranie zadania animacji na podstawie prawidłowego identyfikatora zadania id. Zapoznaj się z sekcją Obiekt zadania animacji, aby zobaczyć, jakie właściwości są zawarte.

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania animacji do pobrania.

Zwraca

Odpowiedź zawiera obiekt zadania animacji. Szczegóły znajdziesz w sekcji Obiekt zadania animacji.

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

Usuń zadanie animacji

Ten punkt końcowy trwale usuwa zadanie animacji, wraz ze wszystkimi powiązanymi modelami i danymi. Ta czynność jest nieodwracalna.

Parametry ścieżki

Name
id
Type
path
Description
ID zadania animacji do usunięcia.

Status zadania

Zadanie, które nadal ma status PENDING, zostaje usunięte, a kredyty zużyte w momencie utworzenia zostają zwrócone.

Zadania, które jest już IN_PROGRESS, nie można usunąć: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie nadal działa. Kredyty za zadanie, które worker już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) zostaje usunięte bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status 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

Zwraca listę zadań animacji wywołującego, stronicowaną, posortowaną od najnowszych. Standardowe stronicowanie za pomocą page_num i page_size.

Należy pamiętać, że zadania utworzone za pośrednictwem API są zarządzane przez API — nie pojawiają się w sekcji Moje zasoby w aplikacji webowej. Użyj tego punktu końcowego, aby odnaleźć zadanie, którego identyfikatora już nie posiadasz.

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

Stream an Animation Task

Ten punkt końcowy przesyła aktualizacje w czasie rzeczywistym dla zadania Animacja za pomocą Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Animacja do przesyłania strumieniowego.

Zwraca

Zwraca strumień Obiektów zadania animacji jako Server-Sent Events.

W przypadku zadań PENDING lub IN_PROGRESS strumień odpowiedzi będzie zawierał tylko niezbędne pola progress i 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
}

Obiekt zadania Animacji

Obiekt zadania Animacji reprezentuje jednostkę pracy związaną z zastosowaniem animacji do postaci z armaturą.

Właściwości

Name
id
Type
string
Description
Unikalny identyfikator zadania.
Name
type
Type
string
Description
Typ zadania Animacji. Wartość to animate.
Name
status
Type
string
Description
Status zadania. Możliwe wartości: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress zadania (0-100).
Name
created_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) wskazujący moment utworzenia zadania.
Znacznik czasu reprezentuje liczbę milisekund, które upłynęły od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład piątek, 1 września 2023, godzina 12:00:00 GMT jest reprezentowana jako 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.
Name
started_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) wskazujący moment rozpoczęcia przetwarzania zadania. 0, jeśli nie rozpoczęto.
Name
finished_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) wskazujący moment zakończenia zadania. 0, jeśli nie zakończono.
Name
expires_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) wskazujący moment wygaśnięcia assetów będących wynikiem zadania.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Zobacz Błędy, aby poznać pełny opis obiektu task_error.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Obecna, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (w przypadku niepowodzenia kredyty są zwracane).
Name
result
Type
object
Description
Zawiera adresy URL wynikowej animacji, jeśli zadanie zakończyło się statusem SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  Adres URL do pobrania animacji w formacie GLB. Dla zadania utworzonego z użyciem action_ids, ten pojedynczy plik zawiera każdą żądaną akcję jako osobny klip.
- Name
  animation_fbx_url
  Type
  string
  Description
  Adres URL do pobrania animacji w formacie FBX. Dla zadania utworzonego z użyciem action_ids, ten pojedynczy plik zawiera każdą żądaną akcję jako osobny klip.
- Name
  processed_usdz_url
  Type
  string
  Description
  Adres URL do pobrania przetworzonej animacji w formacie USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Adres URL do pobrania przetworzonej armatury w formacie FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Adres URL do pobrania animacji ze zmienioną liczbą FPS w formacie FBX (np. jeśli użyto operacji change_fps).
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań w kolejce. Ma znaczenie tylko wtedy, gdy status to 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

List Animations

Zwraca każdą animację w bibliotece, uporządkowaną według action_id. Odpowiedź jest pełną listą, a nie stroną wyników, więc jedno wywołanie wystarczy, aby wypełnić selektor akcji. Filtry zawężają wynik; pomiń je wszystkie, aby pobrać wszystko.

Aby przeglądać ten sam katalog wzrokowo, z animowanym podglądem każdej akcji, zobacz dokumentację Biblioteki animacji.

Ten punkt końcowy jest darmowy — nie zużywa kredytów.

Parametry

Name
search
Type
string
Description
Dopasowanie podciągu bez rozróżniania wielkości liter w name lub key. Dopasowywane dosłownie, więc % i _ są zwykłymi znakami, a nie symbolami wieloznacznymi.
Name
category
Type
string
Description
Dokładne dopasowanie do category.
Dostępne wartości:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Dokładne dopasowanie do sub_category. Akceptowane samodzielnie — nazwy podkategorii nie są unikalne we wszystkich kategoriach (Transitioning występuje zarówno w Fighting, jak i DailyActions), więc bez category filtr dopasowuje tę podkategorię wszędzie tam, gdzie się pojawia.
Name
action_ids
Type
string
Description
Rozdzielona przecinkami lista wartości action_id do zwrócenia, służąca do rozwiązywania konkretnych identyfikatorów zamiast przeglądania. Akceptuje maksymalnie 200 identyfikatorów. Identyfikatory, których nie ma żadna animacja, są po prostu nieobecne w odpowiedzi, więc możesz również użyć tego do sprawdzenia, czy przechowywane przez Ciebie identyfikatory są nadal dostępne.

Łączenie filtrów

Filtry są stosowane łącznie — każdy z nich dodatkowo zawęża wynik, więc animacja jest zwracana tylko wtedy, gdy spełnia wszystkie z nich. W obrębie pojedynczego filtra wiele wartości dopasowuje którąkolwiek z nich: search dopasowuje name lub key, a action_ids dopasowuje dowolny identyfikator z listy.

Oznacza to, że kombinacja bez części wspólnej zwraca pustą tablicę zamiast błędu. Akcja 92 to „Double Combo Attack”, animacja z kategorii Fighting:

?action_ids=92&category=Fighting zwraca akcję 92.
?action_ids=92&category=Dancing zwraca [] — nie jest to animacja Dancing.
?action_ids=92&search=walk zwraca [] — jej nazwa nie pasuje do walk.

Aby pobrać konkretne animacje niezależnie od ich kategorii, przekaż samodzielnie action_ids.

Zwraca

Zwraca listę Obiektów Animacji.

Każdy action_id zwrócony tutaj jest akceptowany przez Utwórz zadanie animacji powyżej, a każdy identyfikator, który on akceptuje, jest zwracany tutaj. Wycofane animacje są nieobecne w obu przypadkach. Jeśli buforujesz bibliotekę, odświeżaj ją okresowo, aby wycofany identyfikator nie utrzymywał się w Twoim selektorze.

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

Obiekt Animacji

Name
action_id
Type
integer
Description
Wartość przekazywana jako action_id podczas tworzenia zadania animacji. Unikalna i stabilna, ale nieciągła — wycofane animacje pozostawiają luki w numeracji, więc nigdy nie zakładaj, że zakres id jest prawidłowy.
Name
name
Type
string
Description
Czytelna dla człowieka etykieta, do wyświetlania. Nieunikalna: niektóre animacje mają tę samą nazwę co inny wariant, więc jako identyfikator używaj action_id lub key.
Name
key
Type
string
Description
Unikalny, stabilny slug animacji. Użyj go, gdy potrzebujesz nienumerycznego identyfikatora do indeksowania własnego magazynu danych.
Name
category
Type
string
Description
Grupowanie najwyższego poziomu, np. Fighting.
Name
sub_category
Type
string
Description
Grupowanie w ramach kategorii, np. AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL animowanego pliku GIF prezentującego akcję, nadający się do bezpośredniego renderowania we własnym selektorze.

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