API Animacji

Endpointy do wykrywania dostępnych animacji oraz stosowania ich na postaciach z rigiem.

POST/openapi/v1/animations

Create an Animation Task

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 postprocessingu.

Zadanie jest wykonywane w tle. Informacje o tym, ile zwykle to trwa, znajdziesz w sekcji Czas przetwarzania.

Parametry

Name
rig_task_id
Type
string
Wymagane
Description
id pomyślnie ukończonego zadania riggingu (z POST /openapi/v1/rigging). Postać z tego zadania zostanie poddana animacji.
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 jeden z parametrów: action_id, action_ids lub motion_task_id.
Name
action_ids
Type
array of integers
Description
Kilka gotowych akcji animacji do zastosowania jednocześnie, zwróconych jako pojedynczy plik zawierający jeden klip animacji na akcję — przydatne przy sterowaniu postacią z 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 jeden z parametrów: action_id, action_ids lub motion_task_id.
Przekazanie jednoelementowej tablicy action_ids jest równoważne przekazaniu tej wartości jako action_id.
Name
motion_task_id
Type
string
Description
id pomyślnie ukończonego zadania Text to Motion, które ma zostać zastosowane zamiast gotowej akcji. Wygenerowany klip jest retargetowany na zriggowaną postać, a klip jest utrwalany (snapshot) w momencie tworzenia zadania, dzięki czemu to zadanie nie jest dotknięte, 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 riggu dwunożnego (biped). Podaj dokładnie jeden z parametrów: action_id, action_ids lub motion_task_id.
Name
post_process
Type
object
Description
Opcjonalny postprocessing dla wyjściowej animacji. Pomiń, aby otrzymać standardowe pliki animacji.

Dotyczy tylko gdy post_process is set

Name
operation_type
Type
string
Wymagane
Description
Typ 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.

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

Kolejność klipów: kolejność z tablicy action_ids, a nie numeryczna kolejność identyfikatorów.
Nazwy klipów: nazwa animacji w bibliotece, zgodna z nazwami, które otrzymujesz podczas eksportowania wszystkich animacji postaci jako pojedynczego pliku z aplikacji webowej Meshy. Jeśli dwa żądane identyfikatory odwołują się do tej samej nazwy klipu, późniejszy otrzymuje sufiks w postaci jego action_id, aby zachować unikalność nazw.
Postprocessing: stosowany do połączonego pliku, a nie do poszczególnych klipów.

Przy użyciu motion_task_id retargetowanie może wygenerować animację tylko w formacie GLB. Jeśli zażądano post_process, a 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ę powodzeniem, 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:
- Brak parametru: brakuje rig_task_id lub nie podano żadnego z parametrów action_id, action_ids i motion_task_id.
- Konfliktujące parametry: podano więcej niż jeden z parametrów action_id, action_ids i motion_task_id — wzajemnie się one wykluczają.
- Nieprawidłowe zadanie riggingu: rig_task_id jest nieprawidłowy lub odnosi się do nieudanego/nieistniejącego zadania.
- Nieprawidłowy identyfikator akcji: action_id — lub jeden z elementów action_ids — nie odpowiada 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 wskazane przez motion_task_id nie ma jeszcze statusu SUCCEEDED.
- Nieobsługiwany rig: motion_task_id wymaga riggu dwunożnego (biped); 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

Pobierz zadanie animacji

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

Parametry

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

Zwracane dane

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

Usuwanie zadania animacji

Ten punkt końcowy trwale usuwa zadanie animacji, w tym wszystkie powiązane modele i dane. Ta operacja jest nieodwracalna.

Parametry ścieżki

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

Status zadania

Zadanie, które wciąż ma status PENDING, jest usuwane, a kredyty zużyte w momencie utworzenia są zwracane.

Zadanie, które jest już w stanie IN_PROGRESS, nie może zostać usunięte: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie nadal się wykonuje. Kredyty za zadanie, które worker już rozpoczął przetwarzać, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby 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) jest usuwane bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie jest w stanie 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 stronicowaną listę zadań Animacji wywołującego, od najnowszych. Standardowe stronicowanie za pomocą page_num i page_size.

Zwróć uwagę, że zadania utworzone za pomocą API są zarządzane przez API — nie pojawiają się w sekcji Moje zasoby aplikacji webowej. Użyj tego punktu końcowego, aby znaleźć zadanie, którego ID 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

Przesyłanie strumieniowe zadania animacji

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

Parametry

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

Zwraca

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

Dla 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 polegającą na zastosowaniu animacji do postaci z riggiem.

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
Postęp zadania (0-100).
Name
created_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) utworzenia zadania.
Znacznik czasu reprezentuje liczbę milisekund, która upłynęła od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład piątek, 1 września 2023, godzina 12:00:00 czasu 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) rozpoczęcia przetwarzania zadania. 0, jeśli nie rozpoczęto.
Name
finished_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) zakończenia zadania. 0, jeśli nie zakończono.
Name
expires_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) wygaśnięcia zasobów wynikowych zadania.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Pełny opis obiektu task_error znajdziesz w sekcji Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Dostępna, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).
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. W przypadku zadania utworzonego z 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. W przypadku zadania utworzonego z 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ą klatek na sekundę w formacie FBX (np. jeśli użyto operacji change_fps).
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań w kolejce. Istotna 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 kompletną 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 odnośnik do 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 category.
Dostępne wartości:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Dokładne dopasowanie sub_category. Akceptowany samodzielnie — nazwy podkategorii nie są unikalne w obrębie kategorii (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
Lista wartości action_id rozdzielonych przecinkami do zwrócenia, służąca do rozwiązywania konkretnych id, a nie do przeglądania. Akceptuje maksymalnie 200 id. Id, których nie posiada żadna animacja, po prostu nie pojawiają się w odpowiedzi, więc możesz też użyć tego do sprawdzenia, czy przechowywane przez Ciebie id 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 je wszystkie. W ramach pojedynczego filtra, wiele wartości dopasowuje się, jeśli spełniona jest którakolwiek z nich: search dopasowuje name lub key, a action_ids dopasowuje dowolne id 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 z kategorii Dancing.
?action_ids=92&search=walk zwraca [] — jej nazwa nie pasuje do walk.

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

Zwraca

Zwraca listę Obiektów Animacji.

Każde action_id zwrócone tutaj jest akceptowane przez Create an Animation Task powyżej, a każde id, które ten punkt końcowy akceptuje, jest tutaj zwracane. Wycofane animacje są nieobecne w obu przypadkach. Jeśli buforujesz bibliotekę, odświeżaj ją okresowo, aby wycofane id nie pozostawało 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 dany zakres identyfikatorów jest poprawny.
Name
name
Type
string
Description
Czytelna dla człowieka etykieta, do wyświetlania. Nieunikalna: niektóre animacje dzielą tę samą nazwę z inną wersją, więc jako identyfikator używaj action_id lub key.
Name
key
Type
string
Description
Unikalny, stabilny identyfikator tekstowy (slug) animacji. Używaj 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
Adres URL animowanego obrazu 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"
}