API Анимации

Применяйте анимации к персонажам с ригом и получайте список анимаций, которые можно применить.

POST/openapi/v1/animations

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

Создаёт задачу Анимации, которая применяет анимацию к персонажу, которого вы ранее риггировали. Анимацией может быть один из следующих вариантов:

Готовое действие из библиотеки анимаций (action_id)
Несколько готовых действий, объединённых в один файл (action_ids)
Клип движения, сгенерированный с помощью Text to Motion API (motion_task_id)

Вы также можете выполнить постобработку результата. Задача выполняется в фоновом режиме. Сколько обычно занимает задача, см. в разделе Время обработки.

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

Параметры

Name
rig_task_id
Type
string
Обязательный
Description
ID задачи Rigging, персонажа из которой нужно анимировать, из POST /openapi/v1/rigging. Задача должна иметь статус SUCCEEDED.

Отправьте ровно один из параметров: action_id, action_ids или motion_task_id.

Name
action_id
Type
integer
Обязательный
Description
Обязателен, если не отправлены action_ids или motion_task_id. ID готовой анимации, которую нужно применить. Полный список анимаций см. в справочнике Библиотека анимаций или Список анимаций.

Name
action_ids
Type
array of integers
Обязательный
Description
Обязателен, если не отправлены action_id или motion_task_id. ID от 1 до 10 готовых анимаций, которые нужно применить одновременно, без повторов. Если указано больше 10 ID или ID повторяется, возвращается ошибка 400. Список ID см. в справочнике Библиотека анимаций.
Meshy возвращает один файл с одним анимационным клипом на каждое действие, что подходит для машины состояний в игровом движке. Meshy взимает плату за каждое действие в списке. См. Цены.
Список с одним ID работает так же, как отправка этого ID в параметре action_id.

Name
motion_task_id
Type
string
Обязательный
Description
Обязателен, если не отправлены action_id или action_ids. ID задачи Text to Motion, клип которой нужно применить вместо готового действия. Задача должна иметь статус SUCCEEDED, а скелет должен быть двуногим (biped).
Meshy ретаргетирует клип на риггированного персонажа. Клип копируется в момент создания этой задачи, поэтому данная задача не зависит от того, истечёт ли срок действия задачи Text to Motion позже или будет ли она удалена. Meshy хранит файлы задачи Text to Motion в течение 3 дней, поэтому применяйте клип до истечения этого срока.

Name
post_process
Type
object
Description
Постобработка для результата анимации. Не указывайте этот параметр, чтобы получить стандартные файлы анимации.
При использовании motion_task_id ретаргетинг может дать на выходе анимацию только в формате GLB. Если вы отправите post_process, а файл FBX недоступен, задача завершится с ошибкой task_error, и Meshy вернёт ваши кредиты. Без post_process задача завершается успешно, а animation_fbx_url будет пустым.

Применяется только когда post_process is set

Name
operation_type
Type
string
Description
Операция для выполнения. Без неё Meshy не создаёт дополнительный файл. Значение, отсутствующее в списке ниже, возвращает ошибку 400.
Доступные значения:
- change_fps: изменяет частоту кадров на fps
- fbx2usdz: конвертирует анимацию в USDZ
- extract_armature: извлекает арматуру в виде файла FBX
Name
fps
Type
integer
по умолчанию 30
Description
Частота кадров, на которую нужно изменить: 24, 25, 30 или 60. Применяется только если operation_type равен change_fps. Любое другое значение возвращает ошибку 400.

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

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

Возвращаемые данные

Поле 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: rig_task_id не является допустимым ID задачи, не относится к задаче Rigging, или указывает на задачу, которая не завершилась успешно.
- Недопустимый ID действия: action_id или одно из значений в action_ids не является допустимой анимацией.
- Слишком много действий: в action_ids указано более 10 ID.
- Дублирующиеся действия: в action_ids один и тот же ID указан более одного раза.
- Задача motion не готова: задача motion_task_id ещё не достигла статуса SUCCEEDED.
- Неподдерживаемый скелет: motion_task_id требует двуногий (biped) скелет, и Meshy отклоняет четвероногий (quadruped) скелет.
Исправьте запрос и отправьте его снова. См. Ошибки.
Name
401 - Unauthorized
Description
API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.
Name
402 - Payment Required
Description
Например:
- Недостаточно кредитов: на аккаунте недостаточно кредитов для этой задачи, либо аккаунт достиг лимита кредитов. Проверьте баланс кредитов и повторите попытку.
- Бесплатный план: для создания задачи требуется платный план. Обновите свой план в настройках подписки, затем повторите попытку.
Name
403 - Forbidden
Description
Задача rig_task_id относится к барельефной модели, которую этот эндпоинт не может анимировать. Сообщение: This model type does not support this operation. Риггируйте другую модель.
Name
404 - Not Found
Description
Meshy не может найти задачу или файл, необходимый для запроса. Применимо одно из следующего:
- Meshy не может найти задачу rig_task_id среди ваших задач. Проверьте ID.
- Meshy удалила файлы задачи rig_task_id после истечения срока expires_at. Риггируйте персонажа заново.
- Meshy не может найти задачу motion_task_id. Проверьте ID.
- Срок действия клипа движения истёк, так как Meshy хранит файлы задачи Text to Motion в течение 3 дней. Создайте новую задачу Text to Motion.
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты запросов. Подождите и повторите попытку. См. Ограничения частоты.

GET/openapi/v1/animations/:id

Получить задачу Анимации

Возвращает задачу Анимации по её ID.

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": null,
  "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=..."
  }
}

Параметры

Name
id
Type
path
Description
ID задачи из ответа на создание.

Возвращает

Объект задачи Анимации.

DELETE/openapi/v1/animations/:id

Удаление задачи Анимации

Безвозвратно удаляет задачу Анимации, включая её модели и данные. Отменить удаление невозможно.

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

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

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

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

Удаление задачи со статусом PENDING возвращает кредиты, потраченные на её создание.

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

Удаление задачи с финальным статусом (SUCCEEDED, FAILED или CANCELED) не возвращает кредиты.

Возвращает

200 OK, когда задача удалена, либо 409 Conflict, когда задача имеет статус IN_PROGRESS.

GET/openapi/v1/animations

Получение списка задач Анимации

Возвращает постраничный список ваших задач Анимации, начиная с самых новых. Для постраничной навигации по списку используйте page_num и page_size.

Задачи, созданные через API, не отображаются в разделе My Assets в веб-приложении, поэтому управлять ими нужно через API. Чтобы найти задачу, идентификатор которой у вас больше не сохранён, используйте этот эндпоинт.

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

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.
// These examples are shortened. Each event holds the full task object.
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, with the same structure as the 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": null,
  "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?..."
  }
}

Параметры

Name
id
Type
path
Description
ID задачи из ответа на создание.

Возвращает

Поток объектов задачи Анимации в виде Server-Sent Events.

Каждое событие содержит полный объект задачи, в том же формате, что возвращает эндпоинт Get. Пока задача находится в статусе PENDING или IN_PROGRESS, поля результата ещё не имеют значений.

Объект задачи Animation

Объект задачи Animation описывает одну анимацию, применённую к риггованному персонажу. Он содержит статус, progress и файлы анимации, когда задача завершается успешно.

Свойства

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": null,
  "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?..."
  }
}

Name
id
Type
string
Description
ID задачи. Рассматривайте его как непрозрачную строку и не полагайтесь на её формат.
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
Время создания задачи, в миллисекундах Unix.
Name
started_at
Type
timestamp
Description
Время начала задачи, в миллисекундах Unix. Значение равно 0, пока задача не началась.
Name
finished_at
Type
timestamp
Description
Время завершения задачи, в миллисекундах Unix. Значение равно 0, пока задача не завершится.
Name
expires_at
Type
timestamp
Description
Время истечения срока действия файлов результата задачи, в миллисекундах Unix.
Name
task_error
Type
object
Description
Детали ошибки, если задача завершилась неудачей. Значение равно null, если статус не FAILED. См. Ошибки.
Name
consumed_credits
Type
integer
Description
Количество кредитов, использованных задачей. Присутствует, когда статус — PENDING, IN_PROGRESS или SUCCEEDED. Для задачи со статусом FAILED значение равно 0, потому что Meshy возвращает кредиты при неудачном выполнении задачи.
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
  Анимация с изменённой частотой кадров в виде файла FBX, например, если вы использовали операцию change_fps.
Name
preceding_tasks
Type
integer
Description
Количество задач перед данной в очереди. Значение имеет смысл только пока задача имеет статус PENDING. Поле отсутствует, если значение равно 0.

GET/openapi/v1/animations/library

Получить список анимаций

Возвращает все анимации в библиотеке, упорядоченные по action_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"
  }
]

Параметры

Name
search
Type
string
Description
Текст для поиска. Meshy возвращает анимации, у которых name или key содержит этот текст, без учёта регистра. Meshy сопоставляет текст буквально, поэтому % и _ не являются подстановочными символами.
Name
category
Type
string
Description
Категория для вывода, точное совпадение. Неизвестная категория возвращает пустой список.
Доступные значения:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Подкатегория для вывода, точное совпадение. Можно указать её без category. Названия подкатегорий не уникальны в разных категориях. Например, Transitioning встречается и в Fighting, и в DailyActions. Поэтому без category фильтр сопоставляет подкатегорию во всех категориях.
Name
action_ids
Type
string
Description
Анимации, которые нужно вернуть, — до 200 значений action_id, разделённых запятыми. Используйте этот параметр, чтобы находить конкретные ID, а не просматривать список. Более 200 ID вернёт 400.
В ответе не будет ID, которому не соответствует ни одна анимация. Поэтому этот фильтр можно также использовать, чтобы проверить, доступны ли ещё сохранённые у вас ID.

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

Meshy применяет фильтры совместно. Каждый из них сужает результат, поэтому Meshy возвращает анимацию, только если она соответствует всем фильтрам сразу. Внутри одного фильтра совпадение может быть по любому из его значений. Например, 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 не оставался в вашем селекторе.

Объект анимации

Объект анимации описывает одну анимацию в библиотеке.

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

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-превью действия. Вы можете показывать его прямо в собственном средстве выбора.