API для Риггінгу

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

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

POST/openapi/v1/rigging

Створення завдання з ригінгу

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

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

Меші без текстур
Негуманоїдні assets
Гуманоїдні assets з нечіткою структурою кінцівок і тіла

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

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

Параметри

Тільки один з input_task_id або model_url є обов'язковим. Якщо обидва надані, input_task_id має пріоритет.

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

Name
model_url
Type
string
Обов'язковий
Description
Будь ласка, надайте 3D модель для Meshy для ригінгу через загальнодоступний URL або Data URI. Наразі ми підтримуємо текстуровані гуманоїдні GLB файли (формат .glb).

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

Повертає

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

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

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

Запит

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
  }'

Відповідь

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

GET/openapi/v1/rigging/:id

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

Ця кінцева точка дозволяє отримати завдання з риггінгу за дійсним id завдання. Зверніться до Об'єкт завдання з риггінгу, щоб побачити, які властивості включені.

Параметри

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

Повертає

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

Запит

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}"

Відповідь

{
  "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

Видалення завдання з ригінгу

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

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

Name
id
Type
path
Description
Ідентифікатор завдання з ригінгу, яке потрібно видалити.

Повертає

Повертає 200 OK у разі успіху.

Запит

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}"

Відповідь

// Returns 200 Ok on success.

GET/openapi/v1/rigging

Перелік завдань з ригінгу

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

Зверніть увагу, що завдання, створені через API, керуються через API — вони не з'являються у розділі Мої Активи веб-застосунку. Використовуйте цю кінцеву точку, щоб знайти завдання, ідентифікатор якого ви більше не маєте.

Запит

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.

Запит

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
}

Об'єкт Завдання Rigging

Об'єкт Завдання Rigging представляє одиницю роботи для додавання скелета до персонажа.

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор для завдання.
Name
type
Type
string
Description
Тип завдання Rigging. Значення - 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 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-адреси вихідних 3D-активів, якщо завдання 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 було неявно увімкнено або увімкнено за замовчуванням).
  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
}