Rigging API

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

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

POST/openapi/v1/rigging

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

Створює завдання Rigging для 3D-моделі. Коли завдання виконується успішно, воно повертає ригований персонаж у стандартних форматах і, за бажанням, базові анімації ходьби та бігу.

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

Rigging не підходить для таких моделей:

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

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

Параметри

Name
input_task_id
Type
string
Обов'язковий
Description
Обов'язково, якщо ви не надсилаєте model_url. ID завдання, модель якого ви хочете риговати. Meshy підтримує текстуровані людиноподібні моделі.
Модель може мати щонайбільше 380 000 трикутників (квад рахується як 2), і модель з більшою кількістю повертає 400. Щоб не перевищувати ліміт, спочатку запустіть Remesh API з target_polycount 300000 або менше, або 150000 або менше з topology: quad.

Name
model_url
Type
string
Обов'язковий
Description
Обов'язково, якщо ви не надсилаєте input_task_id. Модель для ригінгу, у вигляді публічного URL або data URI. Якщо ви надсилаєте обидва, Meshy використовує input_task_id.
Модель має бути файлом GLB (.glb) розміром щонайбільше 400 МБ з URL http або https, або 100 МБ у вигляді data URI. Rigging підтримує текстуровані людиноподібні моделі.
Модель може мати щонайбільше 380 000 трикутників (квад рахується як 2), і модель з більшою кількістю повертає 400. Щоб не перевищувати ліміт, спочатку запустіть Remesh API з target_polycount 300000 або менше, або 150000 або менше з topology: quad.
Обличчя персонажа має бути спрямоване вздовж осі +Z, стандартного напрямку "вперед" у glTF. Оцінка пози не вдається для моделі, повернутої в іншому напрямку.
Файл розміром понад 100 МБ також повинен відповідати таким правилам:
- Він може мати щонайбільше 10 000 000 граней. Файл з більшою кількістю повертає 400. Meshy рахує грані як трикутники, а сітка, намальована більше одного разу, рахується один раз на кожну копію.
- Він не повинен використовувати стиснення Draco.

Name
height_meters
Type
number
за замовчуванням 1.7
Description
Приблизна висота персонажа в метрах. Meshy використовує це значення для точнішого масштабування та ригінгу моделі. Від'ємне значення повертає 400.
Name
texture_image_url
Type
string
⚠ застарілий
Description
Не вказуйте, якщо модель має власні текстури. Без цього параметра Meshy використовує текстури, вбудовані у файл model_url, або текстури вхідного завдання. Якщо ви його надсилаєте, це зображення стає єдиною текстурою ригованої моделі, і модель втрачає свої PBR-карти.
UV-розгорнута базова кольорова текстура моделі, у вигляді публічного URL або data URI. Зображення має бути файлом PNG розміром щонайбільше 20 МБ. Інший формат зображення повертає 400.

Результат

Поле result у відповіді містить ID нового завдання Rigging.

Режими збою

Name
400 - Bad Request
Description
Запит не може бути виконаний. Повідомлення про помилку вказує, яку проблему виявлено. Наприклад:
- Відсутній параметр: не надіслано ні model_url, ні input_task_id.
- Недійсний формат моделі: файл model_url має непідтримуване розширення. Підтримується лише .glb.
- Недоступний URL: Meshy не може завантажити файл model_url.
- Файл моделі завеликий: файл model_url перевищує 400 МБ з URL http або https, або перевищує 100 МБ як data URI.
- Забагато граней: файл model_url перевищує 100 МБ і має понад 10 000 000 граней. Зменште кількість граней, потім надішліть файл знову.
- Непридатний для читання файл моделі: файл model_url перевищує 100 МБ, і Meshy не може прочитати його заголовок. Наприклад, це GLB, стиснений Draco.
- Заголовок моделі занадто складний: файл model_url перевищує 100 МБ, і його заголовок має забагато сіток, вузлів або записів для перевірки. Зменште кількість об'єктів у файлі, потім надішліть його знову.
- Зображення завелике: зображення texture_image_url перевищує 20 МБ.
- Недійсний формат текстури: зображення texture_image_url не є файлом PNG.
- Недійсна висота: height_meters від'ємне.
- Недійсне вхідне завдання: input_task_id не посилається на дійсне завдання API.
- Вхідне завдання не готове: завдання input_task_id ще не досягло стану SUCCEEDED. Зачекайте, поки воно виконається успішно, потім повторіть спробу.
- Перевищено кількість граней: вхідна модель має понад 380 000 трикутників (квад рахується як 2). Запустіть Remesh API з target_polycount 300000 або менше, або 150000 або менше з topology: quad, перед тим як риговати модель.
Виправте запит, потім надішліть його знову. Див. Помилки.
Name
401 - Unauthorized
Description
API-ключ відсутній або недійсний. Перевірте заголовок Authorization.
Name
402 - Payment Required
Description
Наприклад:
- Недостатньо кредитів: на обліковому записі недостатньо кредитів для цього завдання, або обліковий запис досяг ліміту кредитів. Перевірте баланс кредитів, потім повторіть спробу.
- Безкоштовний план: для створення завдання потрібен платний план. Оновіть свій план у налаштуваннях підписки, потім повторіть спробу.
Name
403 - Forbidden
Description
input_task_id — це модель барельєфу, яку ця кінцева точка не може риговати. Повідомлення: This model type does not support this operation. Надішліть іншу модель.
Name
404 - Not Found
Description
Meshy не може знайти файли завдання input_task_id. Застосовується одне з наведеного:
- Meshy видалила файли завдання після настання expires_at. Створіть завдання знову, потім надішліть ID цього завдання.
- Завдання не містить жодного з файлів, необхідних для ригінгу, наприклад попереднього зображення, наприклад завдання Convert. Риговане завдання, з якого воно походить, або надішліть модель як model_url.
Name
422 - Unprocessable Entity
Description
Оцінка пози не вдалася. Можливо, модель не є дійсним людиноподібним персонажем. Надішліть модель людиноподібного персонажа. Для model_url також перевірте, що персонаж спрямований вздовж осі +Z.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти. Зачекайте, потім повторіть спробу. Див. Обмеження частоти.

GET/openapi/v1/rigging/:id

Отримати завдання Rigging

Повертає завдання Rigging за його ID.

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": null,
  "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=..."
    }
  }
}

Параметри

Name
id
Type
path
Description
ID завдання з відповіді на створення.

Повертає

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

DELETE/openapi/v1/rigging/:id

Видалення завдання Rigging

Остаточно видаляє завдання Rigging, включно з його моделями та даними. Скасувати видалення неможливо.

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 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
Ідентифікатор завдання, яке потрібно видалити.

Статус завдання

Видалення завдання зі статусом PENDING повертає кредити, витрачені на його створення.

Завдання зі статусом IN_PROGRESS видалити не можна. Запит повертає 409 Conflict, а завдання продовжує виконуватися. Meshy не повертає кредити за завдання, яке вже почало виконуватися, тому видалення такого завдання коштувало б вам і кредитів, і результату. Зачекайте, доки воно не досягне статусу SUCCEEDED, FAILED або CANCELED, а потім видаліть його.

Видалення завдання у фінальному статусі (SUCCEEDED, FAILED або CANCELED) не повертає витрачені на нього кредити.

Повертає

200 OK, коли завдання видалено, або 409 Conflict, коли завдання має статус IN_PROGRESS.

GET/openapi/v1/rigging

Перелік завдань Rigging

Повертає розбитий на сторінки список ваших завдань 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).

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.
// These examples are shortened. Each event holds the full task object.
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 event, with the same fields as the 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": null,
  "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?..."
    }
  }
}

Параметри

Name
id
Type
path
Description
ID задачі з відповіді на створення.

Повертає

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

Кожна подія містить повний об'єкт задачі, у тому ж форматі, що повертає кінцева точка Get. Поки задача має статус PENDING або IN_PROGRESS, її поля результату ще не мають значень.

Об'єкт задачі ріггінгу

Об'єкт задачі ріггінгу описує ріггінг одного персонажа. Він містить статус, progress і вихідні файли, коли задача завершується успішно.

Властивості

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": null,
  "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=..."
    }
  }
}

Name
id
Type
string
Description
ID задачі. Розглядайте його як непрозорий рядок і не покладайтеся на його формат.
Name
type
Type
string
Description
Тип задачі, завжди rig.
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. Після цього часу Meshy може видалити файли.
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-адреси вихідних файлів. Доки задача не завершена успішно, кожна URL-адреса є порожнім рядком, а basic_animations дорівнює 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-адреси для завантаження стандартних анімацій ходьби та бігу.
  Name
  walking_glb_url
  Type
  string
  Description
  Анімація ходьби зі скіном, у форматі GLB.
  Name
  walking_fbx_url
  Type
  string
  Description
  Анімація ходьби зі скіном, у форматі FBX.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Арматура анімації ходьби, у форматі GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Анімація бігу зі скіном, у форматі GLB.
  Name
  running_fbx_url
  Type
  string
  Description
  Анімація бігу зі скіном, у форматі FBX.
  Name
  running_armature_glb_url
  Type
  string
  Description
  Арматура анімації бігу, у форматі GLB.
Name
preceding_tasks
Type
integer
Description
Кількість задач перед цією в черзі. Значення має сенс лише тоді, коли задача має статус PENDING. Поле відсутнє, якщо значення дорівнює 0.