API Анимации

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

POST/openapi/v1/animations

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

Этот эндпоинт позволяет создать новую задачу для применения анимации к ранее заригованному персонажу — либо предустановленное действие из библиотеки анимаций (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 дней — примените клип до истечения этого срока. Требуется двуногий риг. Укажите ровно один из параметров: 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 недействителен или ссылается на неудачную/несуществующую задачу.
- Недействительный ID действия: action_id не соответствует допустимой анимации.
- Задача движения не готова: задача 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 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
}

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

Объект задачи Анимации представляет собой единицу работы по применению анимации к персонажу с настроенным骨骼绑定.

Свойства

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 PM 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
  Ссылка для скачивания анимации в формате GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  Ссылка для скачивания анимации в формате FBX.
- 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
}