API Анимации

Эндпоинты для поиска доступных анимаций и их применения к персонажам с ригом.

POST/openapi/v1/animations

Создание задачи анимации

Этот эндпоинт позволяет создать новую задачу для применения анимации к ранее заригженному персонажу — предустановленному действию из библиотеки анимаций (action_id), нескольким предустановленным действиям, объединённым в один файл (action_ids), или клипу движения, сгенерированному с помощью 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, action_ids или motion_task_id.
Name
action_ids
Type
array of integers
Description
Несколько предустановленных анимационных действий для одновременного применения, возвращаемых в виде одного файла, содержащего по одному анимационному клипу на каждое действие — полезно для управления персонажем из конечного автомата состояний в игровом движке. Укажите от 1 до 10 значений action_id из справочника по библиотеке анимаций; идентификаторы должны быть уникальными. Стоит 3 кредита за действие. Укажите ровно один из параметров: action_id, action_ids или motion_task_id.
Передача action_ids с одним элементом эквивалентна передаче этого значения как action_id.
Name
motion_task_id
Type
string
Description
id успешно завершённой задачи Text to Motion, которую нужно применить вместо предустановленного действия. Сгенерированный клип перепривязывается (ретаргетинг) к заригженному персонажу, а сам клип фиксируется в момент создания, поэтому данная задача не зависит от последующего истечения срока действия или удаления исходной задачи. Активы исходной задачи сохраняются в течение 3 дней — примените клип до истечения этого срока. Требуется двуногий риг. Укажите ровно один из параметров: action_id, action_ids или 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.

При использовании action_ids задача возвращает один объединённый файл вместо отдельного файла на каждое действие: animation_glb_url и animation_fbx_url каждый указывают на единый ассет, содержащий каждое запрошенное действие в виде отдельного клипа.

Порядок клипов: порядок массива action_ids, а не числовой порядок идентификаторов.
Названия клипов: название анимации в библиотеке, совпадающее с названиями, которые вы получаете при экспорте всех анимаций персонажа в виде единого файла из веб-приложения Meshy. Если два запрошенных идентификатора соответствуют одному и тому же названию клипа, к более позднему добавляется суффикс с его action_id для сохранения уникальности имён.
Постобработка: применяется к объединённому файлу, а не к отдельным клипам.

При использовании 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, action_ids и motion_task_id.
- Конфликтующие параметры: указано более одного параметра из action_id, action_ids и motion_task_id — они взаимоисключающие.
- Недействительная задача риггинга: rig_task_id недействителен или ссылается на неудавшуюся/несуществующую задачу.
- Недействительный идентификатор действия: action_id — или один из элементов action_ids — не соответствует действительной анимации.
- Слишком много действий: action_ids содержит более 10 идентификаторов.
- Повторяющиеся действия: action_ids содержит один и тот же идентификатор более одного раза.
- Задача движения не готова: задача motion_task_id ещё не достигла статуса SUCCEEDED.
- Неподдерживаемый риг: motion_task_id требует двуногого рига; четвероногие риги отклоняются.
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 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

Получение задачи анимации

Этот эндпоинт позволяет получить задачу анимации по действительному 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

Delete an Animation Task

Этот эндпоинт безвозвратно удаляет задачу анимации, включая все связанные с ней модели и данные. Это действие необратимо.

Параметры пути

Name
id
Type
path
Description
ID задачи анимации, которую нужно удалить.

Статус задачи

Задача, которая всё ещё находится в статусе PENDING, удаляется, а кредиты, списанные при создании, возвращаются.

Задача, которая уже находится в статусе IN_PROGRESS, не может быть удалена: запрос отклоняется с ошибкой 409 Conflict, и задача продолжает выполняться. Кредиты за задачу, которую воркер уже начал обрабатывать, не подлежат возврату, поэтому удаление во время выполнения обойдётся вам и в кредиты, и в результат. Дождитесь, пока она перейдёт в статус SUCCEEDED, FAILED или CANCELED, а затем удалите её.

Задача в конечном статусе (SUCCEEDED, FAILED или CANCELED) удаляется без возврата средств.

Возвращаемые значения

Возвращает 200 OK в случае успеха или 409 Conflict, если задача находится в статусе 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

Список задач Анимация

Возвращает список задач анимации вызывающего пользователя с пагинацией, начиная с самых новых. Стандартная пагинация через 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
Тип задачи Анимация. Значение: 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 по Гринвичу представлена как 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
  Ссылка для скачивания анимации в формате GLB. Для задачи, созданной с action_ids, этот единый файл содержит каждое запрошенное действие в виде отдельного клипа.
- Name
  animation_fbx_url
  Type
  string
  Description
  Ссылка для скачивания анимации в формате FBX. Для задачи, созданной с action_ids, этот единый файл содержит каждое запрошенное действие в виде отдельного клипа.
- Name
  processed_usdz_url
  Type
  string
  Description
  Ссылка для скачивания обработанной анимации в формате USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Ссылка для скачивания обработанной арматуры в формате FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Ссылка для скачивания анимации с измененным 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
}

GET/openapi/v1/animations/library

Список анимаций

Возвращает все анимации в библиотеке, упорядоченные по action_id. Ответ представляет собой полный список, а не страницу, поэтому одного вызова достаточно для заполнения селектора действий. Фильтры сужают результат; чтобы получить всё, не указывайте их вовсе.

Чтобы визуально просмотреть тот же каталог с анимированным превью каждого действия, см. справочник Библиотеки анимаций.

Этот эндпоинт бесплатный — он не расходует кредиты.

Параметры

Name
search
Type
string
Description
Поиск подстроки без учёта регистра по name или key. Совпадение ищется буквально, поэтому % и _ являются обычными символами, а не подстановочными знаками.
Name
category
Type
string
Description
Точное совпадение по category.
Доступные значения:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Точное совпадение по sub_category. Принимается самостоятельно — названия подкатегорий не уникальны в разных категориях (Transitioning встречается как в Fighting, так и в DailyActions), поэтому без указания category фильтр находит эту подкатегорию везде, где она встречается.
Name
action_ids
Type
string
Description
Список значений action_id, разделённых запятыми, для получения конкретных id, а не просмотра всего каталога. Принимается не более 200 id. Id, которым не соответствует ни одна анимация, просто отсутствуют в ответе, поэтому это также можно использовать, чтобы проверить, доступны ли ещё сохранённые вами id.

Комбинирование фильтров

Фильтры применяются вместе — каждый из них дополнительно сужает результат, поэтому анимация возвращается, только если она удовлетворяет всем условиям. В рамках одного фильтра несколько значений сопоставляются по принципу «любое из»: search сопоставляется с name или key, а action_ids — с любым id из списка.

Это означает, что комбинация без пересечений возвращает пустой массив, а не ошибку. Действие 92 — это «Double Combo Attack», анимация категории Fighting:

?action_ids=92&category=Fighting возвращает действие 92.
?action_ids=92&category=Dancing возвращает [] — это не анимация категории Dancing.
?action_ids=92&search=walk возвращает [] — его название не соответствует walk.

Чтобы получить конкретные анимации независимо от их категории, передайте action_ids отдельно.

Возвращаемое значение

Возвращает список Объектов анимации.

Каждый action_id, возвращаемый здесь, принимается эндпоинтом Создание задачи анимации выше, и каждый принимаемый им id возвращается здесь. Устаревшие анимации отсутствуют в обоих местах. Если вы кэшируете библиотеку, периодически обновляйте её, чтобы устаревший id не задерживался в вашем селекторе.

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

Объект Animation

Name
action_id
Type
integer
Description
Значение, передаваемое как action_id при создании задачи анимации. Уникально и стабильно, но не идёт подряд — устаревшие анимации оставляют пропуски в нумерации, поэтому никогда не предполагайте, что диапазон id является допустимым.
Name
name
Type
string
Description
Человекочитаемая метка для отображения. Не уникальна: некоторые анимации имеют одно и то же имя, но разные варианты, поэтому в качестве идентификатора используйте action_id или key.
Name
key
Type
string
Description
Уникальный стабильный слаг анимации. Используйте его, если вам нужен нечисловой идентификатор для ключа в вашем собственном хранилище.
Name
category
Type
string
Description
Группировка верхнего уровня, например Fighting.
Name
sub_category
Type
string
Description
Группировка внутри категории, например AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL анимированного GIF-изображения с предпросмотром действия, подходящего для прямого отображения в вашем собственном селекторе.

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