API Анимации

Endpoint'ы для обнаружения доступных анимаций и применения их к персонажам с rig.

POST/openapi/v1/animations

Создать задачу анимации

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

Параметры

Name
rig_task_id
Type
string
Обязательный
Description
id успешно завершённой задачи риггинга (из POST /openapi/v1/rigging). Персонаж из этой задачи будет анимирован.
Name
action_id
Type
integer
Обязательный
Description
Идентификатор анимационного действия, которое нужно применить. Полный список доступных анимаций см. в Справочнике Библиотеки анимаций.
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.

Возвращает

Свойство result в ответе содержит id задачи для новой созданной задачи анимации.

Режимы отказа

Name
400 - Bad Request
Description
Запрос был неприемлемым. Распространённые причины:
- Отсутствует параметр: отсутствует rig_task_id или action_id.
- Недопустимая задача риггинга: rig_task_id недопустим или ссылается на несуществующую задачу либо задачу, завершившуюся с ошибкой.
- Недопустимый ID действия: action_id не соответствует допустимой анимации.
Name
401 - Unauthorized
Description
Не удалось выполнить аутентификацию. Проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
404 - Not Found
Description
Задача риггинга, указанная в rig_task_id, не найдена.
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
  }'

# 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/: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 представляет рабочую единицу для применения анимации к риггированному персонажу.

Свойства

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
Progress задачи (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
Количество кредитов, consumed_credits этой задачей. Присутствует, когда статус задачи — 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
}