Rigging API

Rigging API позволяет программно добавлять скелет (арматуру) к 3D-моделям гуманоидов, связывая с ней сетку, чтобы они были готовы к анимации. Информацию о применении анимаций к риггованному персонажу см. в разделе Animation 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).
Максимальный размер файла: 400 МБ для URL http или https, 100 МБ для data: URI.
Файл размером более 100 МБ с более чем 10 000 000 полигонов возвращает 400. Полигоны считаются как треугольники, а сетка, нарисованная более одного раза, считается один раз за каждую копию. GLB размером более 100 МБ не должен использовать сжатие Draco.

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

Возвращаемое значение

Свойство result ответа содержит id задачи созданной задачи ригинга.

Режимы отказа

Name
400 - Bad Request
Description
Запрос неприемлем. Распространённые причины:
- Отсутствует параметр: должен быть указан либо model_url, либо input_task_id.
- Недопустимый формат модели: model_url указывает на файл с неподдерживаемым расширением (поддерживается только .glb).
- Недоступный URL: не удалось скачать файл по model_url.
- Файл модели слишком большой: файл по model_url превышает 400 МБ (URL http или https) или 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, чтобы уменьшить количество полигонов перед ригингом.
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

Retrieve a Rigging Task

Этот эндпоинт позволяет получить задачу риггинга по действительному 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 задачи на риггинг, которую нужно удалить.

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

Задача, которая всё ещё находится в статусе 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

Трансляция задачи риггинга

Этот эндпоинт передает в реальном времени обновления по задаче риггинга с использованием 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
}

Объект Rigging Task

Объект Rigging Task представляет собой единицу работы по риггингу персонажа.

Свойства

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 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 (с кожей/skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Скачиваемый URL для анимации ходьбы в формате FBX (с кожей/skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Скачиваемый URL для арматуры анимации ходьбы в формате GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Скачиваемый URL для анимации бега в формате GLB (с кожей/skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Скачиваемый URL для анимации бега в формате FBX (с кожей/skin).
  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
}