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 недействителен или ссылается на неудачную/несуществующую задачу.
- Недопустимый 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

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

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

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

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

List Animation Tasks

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

Обратите внимание, что задачи, созданные через API, управляются через 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).

Параметры

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 по Гринвичу представляется как 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. Для задач со статусом FAILED возвращает 0 (кредиты возвращаются при неудаче).
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.

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

Возвращает все анимации из библиотеки, упорядоченные по 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, возвращаемый здесь, принимается эндпоинтом Create an Animation Task выше, и каждый 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"
  }
]

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

Name
action_id
Type
integer
Description
Значение, передаваемое в качестве action_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"
}