API риггинга

API риггинга позволяет программно добавить скелет (арматуру) к 3D-моделям гуманоидов, привязывая к нему сетку, чтобы они были готовы к анимации. Чтобы применить анимации к персонажу с ригом, см. API анимации.

Обратите внимание, что программный риггинг в настоящее время хорошо работает только со стандартными гуманоидными (двуногими) ассетами с четко определенными конечностями и структурой тела.

POST/openapi/v1/rigging

Создание задачи риггинга

Этот эндпоинт позволяет создать новую задачу риггинга для указанной 3D-модели. После успешного завершения он предоставляет персонажа с выполненным риггингом в стандартных форматах и, при необходимости, базовые анимации ходьбы/бега.

В настоящее время автоматический риггинг не подходит для следующих моделей:

Меши без текстуры
Негуманоидные ассеты
Гуманоидные ассеты с неясной структурой конечностей и тела

При использовании input_task_id модели с более чем 300,000 гранями не поддерживаются для риггинга. Используйте 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 граней. Используйте 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
}

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

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

Свойства

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
}