API ригінгу

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

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

POST/openapi/v1/rigging

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

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

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

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

Під час використання 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
Ви перевищили своє обмеження частоти.

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 завдання. Зверніться до Об'єкта завдання ригінгу, щоб побачити, які властивості включено.

Параметри

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

Повертає

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

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

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

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

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

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

Повертає

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

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

// Returns 200 Ok on success.

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

Потокова передача завдання ригінгу

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

Параметри

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

Повертає

Повертає потік об’єктів завдання ригінгу як 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
}

Об’єкт завдання ригінгу

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

Властивості

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
progress завдання (0-100). 0, якщо не розпочато, 100, якщо виконано успішно.
Name
created_at
Type
timestamp
Description
Мітка часу (мілісекунди від початку епохи), коли завдання було створено.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 року, 12:00:00 PM 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-адреси вихідних асетів, якщо завдання 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
}