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
Вы превысили ваше ограничение частоты.

Запрос

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

Ответ

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

Получение задачи по риггингу

Этот эндпоинт позволяет получить задачу по риггингу, используя действительный id задачи. Обратитесь к разделу Объект задачи по риггингу, чтобы увидеть, какие свойства включены.

Параметры

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

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

Ответ содержит объект задачи по риггингу. Проверьте раздел Объект задачи по риггингу для получения деталей.

Запрос

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

Ответ

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

Удаление задачи по rigging

Этот эндпоинт навсегда удаляет задачу по rigging, включая все связанные модели и данные. Это действие необратимо.

Параметры пути

Name
id
Type
path
Description
ID задачи по rigging для удаления.

Возвращает

Возвращает 200 OK в случае успеха.

Запрос

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

Ответ

// Returns 200 Ok on success.

GET/openapi/v1/rigging

Список задач по риггингу

Возвращает список задач по риггингу вызывающего, отсортированный по убыванию. Стандартная пагинация через page_num и page_size.

Обратите внимание, что задачи, созданные через API, управляются через API — они не отображаются в разделе "Мои ассеты" веб-приложения. Используйте этот эндпоинт, чтобы найти задачу, ID которой у вас больше нет.

Запрос

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.

Запрос

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

Поток ответа

// 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
Прогресс выполнения задачи (0-100). 0, если не начато, 100, если успешно завершено.
Name
created_at
Type
timestamp
Description
Временная метка (миллисекунды с начала эпохи), когда задача была создана.
Временная метка представляет собой количество миллисекунд, прошедших с 1 января 1970 года по UTC, в соответствии со стандартом RFC 3339. Например, пятница, 1 сентября 2023 года, 12:00:00 по Гринвичу представляется как 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 был неявно включен или включен по умолчанию).
  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
}