Rigging API

Rigging API дозволяє програмно додавати скелет (арматуру) до 3D-моделей гуманоїдів, прив'язуючи сітку до нього, щоб вони були готові до анімації. Для застосування анімацій до моделі з доданим скелетом див. Animation API.

Зауважте, що наразі програмний ріггінг добре працює лише зі стандартними гуманоїдними (двоногими) активами з чітко визначеними кінцівками та структурою тіла.

POST/openapi/v1/rigging

Створити завдання Rigging

Ця кінцева точка дозволяє створити нове завдання rigging для заданої 3D моделі. Після успішного завершення вона надає персонажа з rig у стандартних форматах і, за бажанням, базові анімації ходьби/бігу.

Завдання виконується у фоновому режимі. Про типову тривалість див. Час обробки.

Наразі авто-rigging не підходить для наступних моделей:

Сітки без текстур
Нелюдиноподібні асети
Людиноподібні асети з нечіткою структурою кінцівок і тіла

При використанні input_task_id моделі з понад 300 000 полігонів не підтримуються для rigging. Будь ласка, використовуйте Remesh API, щоб зменшити кількість полігонів перед rigging.

При використанні model_url обличчя персонажа має бути спрямоване вздовж осі +Z (стандартний напрямок «вперед» у glTF). Моделі, повернуті в інших напрямках, не пройдуть оцінку пози.

Параметри

Потрібен лише один з параметрів input_task_id або model_url. Якщо вказано обидва, пріоритет має input_task_id.

Name
input_task_id
Type
string
Обов'язковий
Description
Вхідне завдання, яке потрібно оснастити rig. Наразі ми підтримуємо текстуровані людиноподібні моделі.

Name
model_url
Type
string
Обов'язковий
Description
Будь ласка, надайте 3D модель для rigging через Meshy за допомогою загальнодоступного URL або Data URI. Наразі ми підтримуємо текстуровані людиноподібні GLB-файли (формат .glb).
Максимальний розмір файлу: 400 МБ для http- або https-URL, 100 МБ для data:-URI.
Файл розміром понад 100 МБ з більш ніж 10 000 000 полігонів повертає 400. Полігони підраховуються як трикутники, а сітка, намальована кілька разів, рахується один раз за кожну копію. GLB розміром понад 100 МБ не повинен використовувати стиснення Draco.

Name
height_meters
Type
number
за замовчуванням 1.7
Description
Приблизна висота моделі персонажа в метрах. Це допомагає підвищити точність масштабування та rigging. Значення має бути додатним числом.
Name
texture_image_url
Type
string
Description
Зображення базової текстури моделі з UV-розгорткою. Загальнодоступний URL або Data URI. Наразі ми підтримуємо формат .png.
Максимальний розмір файлу: 20 МБ.

Повертає

Властивість result у відповіді містить id завдання новоствореного завдання rigging.

Режими відмови

Name
400 - Bad Request
Description
Запит є неприйнятним. Поширені причини:
- Відсутній параметр: Необхідно вказати model_url або input_task_id.
- Невірний формат моделі: model_url вказує на файл з непідтримуваним розширенням (підтримується лише .glb).
- Недоступний URL: Не вдалося завантажити файл за model_url.
- Файл моделі занадто великий: Файл model_url перевищує 400 МБ (http- або https-URL) або 100 МБ (data:-URI).
- Занадто багато полігонів: Файл model_url має розмір понад 100 МБ і містить більш ніж 10 000 000 полігонів. Зменшіть кількість полігонів і надішліть файл знову.
- Нечитабельний файл моделі: Файл model_url має розмір понад 100 МБ, і його заголовок неможливо прочитати, наприклад, GLB зі стисненням Draco.
- Заголовок моделі занадто складний: Файл model_url має розмір понад 100 МБ, і його заголовок містить занадто багато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі та надішліть його знову.
- Зображення занадто велике: Зображення texture_image_url перевищує 20 МБ.
- Недійсне вхідне завдання: input_task_id не посилається на дійсне завдання API.
- Перевищено кількість полігонів: Вхідна модель має понад 300 000 полігонів. Будь ласка, використовуйте Remesh API, щоб зменшити кількість полігонів перед rigging.
Name
401 - Unauthorized
Description
Помилка автентифікації. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
422 - Unprocessable Entity
Description
Оцінка пози не вдалася. Надана модель, можливо, не є дійсним людиноподібним персонажем.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти.

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

Отримати задачу ріггінгу

Ця кінцева точка дозволяє отримати задачу ріггінгу за дійсним id задачі. Перегляньте The Rigging Task Object, щоб побачити, які властивості включені.

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор задачі ріггінгу, яку потрібно отримати.

Повертає

Відповідь містить об'єкт Rigging Task. Перегляньте розділ The Rigging Task Object для деталей.

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

Delete a Rigging Task

Ця кінцева точка остаточно видаляє завдання ріггінгу, включно з усіма пов'язаними моделями та даними. Ця дія незворотна.

Параметри шляху

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/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/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/rigging

Список завдань ригінгу

Повертає пагінований список завдань ригінгу користувача, від найновіших до найстаріших. Стандартна пагінація через page_num та page_size.

Зверніть увагу, що завдання, створені через API, керуються через API — вони не відображаються в розділі My Assets веб-застосунку. Використовуйте цю кінцеву точку, щоб знайти завдання, ID якого у вас більше немає.

Request

GET

/openapi/v1/rigging

curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/rigging/:id/stream

Потокова передача завдання Rigging

Ця кінцева точка передає оновлення в реальному часі для завдання Rigging за допомогою Server-Sent Events (SSE).

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання Rigging для потокової передачі.

Повертає

Повертає потік об'єктів завдання Rigging у вигляді Server-Sent Events.

Для завдань зі статусом PENDING або IN_PROGRESS потік відповіді міститиме лише необхідні поля progress та status.

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

The Rigging Task Object

Об'єкт Rigging Task представляє робочу одиницю для рігінгу персонажа.

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор завдання.
Name
type
Type
string
Description
Тип завдання рігінгу. Значення — rig.
Name
status
Type
string
Description
Статус завдання. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогрес виконання завдання (0-100). 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. Повертає 0 для завдань зі статусом FAILED (кредити повертаються у разі невдачі).
Name
result
Type
object
Description
Містить URL-адреси вихідних ресурсів, якщо завдання завершилося статусом SUCCEEDED, інакше null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL-адреса для завантаження персонажа з рігом у форматі FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL-адреса для завантаження персонажа з рігом у форматі GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Містить URL-адреси для стандартних анімацій. (наприклад, якщо generate_basic_animations було неявно встановлено як true або увімкнено за замовчуванням).
  Name
  walking_glb_url
  Type
  string
  Description
  URL-адреса для завантаження анімації ходьби у форматі GLB (зі шкірою).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL-адреса для завантаження анімації ходьби у форматі FBX (зі шкірою).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL-адреса для завантаження арматури анімації ходьби у форматі GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL-адреса для завантаження анімації бігу у форматі GLB (зі шкірою).
  Name
  running_fbx_url
  Type
  string
  Description
  URL-адреса для завантаження анімації бігу у форматі FBX (зі шкірою).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL-адреса для завантаження арматури анімації бігу у форматі GLB.
Name
preceding_tasks
Type
integer
Description
Кількість попередніх завдань у черзі. Має значення лише якщо статус — PENDING.

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}