API Анімацій

Застосовуйте анімації до персонажів із rig та переглядайте список анімацій, які можна застосувати.

POST/openapi/v1/animations

Створення завдання Анімації

Створює завдання Анімації, яке застосовує анімацію до персонажа, якого ви раніше ріґнули (виконали rigging). Анімація може бути однією з таких:

Готова дія з бібліотеки анімацій (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 готових анімацій для одночасного застосування, без повторів. Якщо ID більше 10 або є повторюваний 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, а rig має бути двоногим.
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_task_id ще не досягло статусу SUCCEEDED.
- Непідтримуваний rig: motion_task_id потребує двоногого rig, і Meshy відхиляє чотириногий rig.
Виправте запит, а потім надішліть його знову. Див. Помилки.
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. Виконайте rigging для іншої моделі.
Name
404 - Not Found
Description
Meshy не може знайти завдання або файл, потрібний для запиту. Застосовується одне з наступного:
- Meshy не може знайти завдання rig_task_id серед ваших завдань. Перевірте ID.
- Meshy видалив файли завдання rig_task_id після настання expires_at. Виконайте rigging персонажа знову.
- 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. Щоб знайти завдання, 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

Stream an Animation task

Транслює оновлення завдання Анімації у вигляді 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. Дорівнює 0 для завдання зі статусом FAILED, оскільки 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
Унікальний, стабільний слаг для анімації. Використовуйте його, коли вам потрібен нечисловий ID для ключування власного сховища.
Name
category
Type
string
Description
Група верхнього рівня, наприклад Fighting.
Name
sub_category
Type
string
Description
Група всередині категорії, наприклад AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL анімованого GIF-прев'ю дії. Ви можете показувати його безпосередньо у власному засобі вибору.