API Анімації

Кінцеві точки для пошуку доступних анімацій та їх застосування до персонажів із rig.

POST/openapi/v1/animations

Створення завдання анімації

Ця кінцева точка дозволяє створити нове завдання для застосування анімації до раніше прив'язаного (rigged) персонажа — або готової дії з бібліотеки анімацій (action_id), або кліпу руху, згенерованого за допомогою Text to Motion API (motion_task_id). Включає параметри постобробки.

Параметри

Name
rig_task_id
Type
string
Обов'язковий
Description
id успішно завершеного завдання прив'язки скелета (з POST /openapi/v1/rigging). Персонаж із цього завдання буде анімовано.
Name
action_id
Type
integer
Description
Ідентифікатор готової анімаційної дії, яку потрібно застосувати. Повний перелік доступних анімацій дивіться в Довіднику бібліотеки анімацій. Потрібно вказати рівно один із параметрів: action_id або motion_task_id.
Name
motion_task_id
Type
string
Description
id успішно завершеного завдання Text to Motion, яке потрібно застосувати замість готової дії. Згенерований кліп ретаргетується на прив'язаного персонажа, а сам кліп фіксується (знімок) на момент створення, тому це завдання не постраждає, якщо вихідне завдання пізніше застаріє або буде видалене. Активи вихідного завдання зберігаються протягом 3 днів — застосуйте кліп до закінчення цього терміну. Потребує прив'язки скелета типу «двонога модель» (biped rig). Потрібно вказати рівно один із параметрів: action_id або motion_task_id.
Name
post_process
Type
object
Description
Необов'язкова постобробка для вихідних даних анімації. Пропустіть цей параметр, щоб отримати стандартні файли анімації.

Застосовується лише коли post_process is set

Name
operation_type
Type
string
Обов'язковий
Description
Тип операції, яку потрібно виконати. Доступні значення: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
за замовчуванням 30
Description
Цільова частота кадрів. Застосовується лише коли operation_type має значення change_fps. Допустимі значення: 24, 25, 30, 60.

При використанні motion_task_id ретаргетинг може створити анімацію лише у форматі GLB. Якщо ви запросили post_process, а файл FBX недоступний, завдання завершується з помилкою task_error, а ваші кредити автоматично повертаються; без post_process завдання виконується успішно, а animation_fbx_url залишається порожнім.

Результат

Властивість result у відповіді містить id завдання щойно створеної анімації.

Режими збоїв

Name
400 - Bad Request
Description
Запит неприйнятний. Поширені причини:
- Відсутній параметр: не вказано rig_task_id, або не вказано жодного з параметрів action_id чи motion_task_id.
- Конфліктуючі параметри: вказано одночасно action_id та motion_task_id — вони є взаємовиключними.
- Недійсне завдання прив'язки: rig_task_id недійсний або посилається на невдале/неіснуюче завдання.
- Недійсний ідентифікатор дії: action_id не відповідає жодній дійсній анімації.
- Завдання руху ще не готове: завдання motion_task_id ще не має статусу SUCCEEDED.
- Непідтримувана прив'язка скелета: motion_task_id вимагає прив'язки типу «двонога модель» (biped rig); прив'язки типу «чотиринога модель» (quadruped rig) відхиляються.
Name
401 - Unauthorized
Description
Помилка автентифікації. Перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
404 - Not Found
Description
Завдання прив'язки скелета, вказане в rig_task_id, не знайдено, завдання руху, вказане в motion_task_id, не знайдено, або термін дії кліпу руху закінчився (активи вихідного завдання зберігаються протягом 3 днів).
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти запитів.

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

Отримання завдання анімації

Ця кінцева точка дозволяє отримати завдання анімації за дійсним id завдання. Див. Об'єкт завдання анімації, щоб побачити, які властивості включені.

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання анімації, яке потрібно отримати.

Повертає

Відповідь містить об'єкт завдання анімації. Перегляньте розділ Об'єкт завдання анімації для деталей.

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

Видалити задачу Анімації

Ця кінцева точка остаточно видаляє задачу анімації, включаючи всі пов'язані моделі та дані. Ця дія є незворотною.

Параметри шляху

Name
id
Type
path
Description
ID задачі анімації, яку потрібно видалити.

Повертає

Повертає 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

Список завдань анімації

Повертає список завдань анімації користувача з пагінацією, спочатку найновіші. Стандартна пагінація через page_num і page_size.

Зверніть увагу, що завдання, створені через API, керуються через API — вони не з'являються в розділі «Мої активи» веб-застосунку. Використовуйте цю кінцеву точку, щоб знайти завдання, ID якого ви більше не маєте.

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

Стрімінг завдання анімації

Ця кінцева точка транслює оновлення в реальному часі для завдання анімації за допомогою Server-Sent Events (SSE).

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання анімації для стрімінгу.

Повертає

Повертає потік об'єктів завдання анімації у вигляді Server-Sent Events.

Для завдань зі статусом PENDING або IN_PROGRESS потік відповіді міститиме лише необхідні поля progress та 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 Task

Об'єкт Animation Task представляє робочу одиницю для застосування анімації до персонажа з прив'язаним скелетом.

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор завдання.
Name
type
Type
string
Description
Тип завдання Animation. Значення: animate.
Name
status
Type
string
Description
Статус завдання. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогрес виконання завдання (0-100).
Name
created_at
Type
timestamp
Description
Мітка часу (у мілісекундах з початку епохи) створення завдання.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року за UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 року, 12:00:00 за GMT представлена як 1693569600000. Це стосується всіх міток часу в Meshy API.
Name
started_at
Type
timestamp
Description
Мітка часу (у мілісекундах з початку епохи) початку обробки завдання. 0, якщо обробку не розпочато.
Name
finished_at
Type
timestamp
Description
Мітка часу (у мілісекундах з початку епохи) завершення завдання. 0, якщо не завершено.
Name
expires_at
Type
timestamp
Description
Мітка часу (у мілісекундах з початку епохи), коли активи результату завдання втратять чинність.
Name
task_error
Type
object
Description
Деталі помилки для невдалих завдань. Див. Помилки для повного опису об'єкта task_error.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, витрачених на це завдання. Присутнє, коли статус завдання — PENDING, IN_PROGRESS або SUCCEEDED. Повертає 0 для завдань зі статусом FAILED (кредити повертаються у разі невдачі).
Name
result
Type
object
Description
Містить URL-адреси вихідної анімації, якщо завдання завершилося зі статусом SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL-адреса для завантаження анімації у форматі GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL-адреса для завантаження анімації у форматі FBX.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL-адреса для завантаження обробленої анімації у форматі USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL-адреса для завантаження обробленої арматури у форматі FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL-адреса для завантаження анімації зі зміненою частотою кадрів (FPS) у форматі FBX (наприклад, якщо було використано операцію change_fps).
Name
preceding_tasks
Type
integer
Description
Кількість завдань, що передують у черзі. Має значення лише якщо статус — 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
}