Rigging API

Добавьте скелет (арматуру) к гуманоидной 3D-модели и привяжите сетку к нему, чтобы персонаж был готов к анимации. Чтобы применить анимации к персонажу с ригом, см. 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

Получить задачу риггинга

Возвращает задачу риггинга по её 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 задачи из ответа на создание.

Возвращает

Объект задачи риггинга.

DELETE/openapi/v1/rigging/:id

Удаление задачи риггинга

Безвозвратно удаляет задачу риггинга, включая её модели и данные. Отменить удаление невозможно.

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
ID задачи, которую нужно удалить.

Статус задачи

Удаление задачи со статусом 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

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

Передаёт обновления задачи риггинга в виде событий 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 задачи из ответа на создание.

Возвращает

Поток объектов задачи риггинга в виде событий 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
  Анимация ходьбы с кожей (skin), в виде файла GLB.
  Name
  walking_fbx_url
  Type
  string
  Description
  Анимация ходьбы с кожей (skin), в виде файла FBX.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Арматура анимации ходьбы, в виде файла GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Анимация бега с кожей (skin), в виде файла GLB.
  Name
  running_fbx_url
  Type
  string
  Description
  Анимация бега с кожей (skin), в виде файла FBX.
  Name
  running_armature_glb_url
  Type
  string
  Description
  Арматура анимации бега, в виде файла GLB.
Name
preceding_tasks
Type
integer
Description
Количество задач перед этой в очереди. Значение имеет смысл только пока задача находится в статусе PENDING. Поле отсутствует, если значение равно 0.