Rigging API

为人形 3D 模型添加骨骼（armature）并将 mesh 绑定到该骨骼上，使角色做好动画准备。要将 Animation 应用到已绑定骨骼的角色上，请参阅 Animation API。

Rigging 仅适用于具有清晰肢体和身体结构的标准人形（两足）角色。

POST/openapi/v1/rigging

创建一个 Rigging 任务

为 3D 模型创建一个 Rigging 任务。任务成功后，会返回一个标准格式的绑定骨骼角色，并可选择性地附带基础的行走和跑步动画。

该任务在后台运行。有关任务通常需要多长时间，请参阅处理时间。

Rigging 不适用于以下模型：

未附带 texture 的 mesh
非人形 asset
四肢和身体结构不清晰的人形 asset

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，否则此项为必填。要进行 rigging 的模型所属任务的 ID。Meshy 支持带 texture 的人形模型。
模型最多可有 320,000 个面，超过此数量的模型将返回 400。为保持在限制范围内，请先对其运行 Remesh API，并将 target_polycount 设置为 300000 或更低。

Name
model_url
Type
string
必选
Description
除非发送 input_task_id，否则此项为必填。要绑定骨骼的模型，可以是公开 URL 或 Data URI。如果两者都发送，Meshy 将使用 input_task_id。
该模型必须是 GLB（.glb）文件，通过 http 或 https URL 提供时最大为 400 MB，作为 Data URI 提供时最大为 100 MB。Rigging 支持带 texture 的人形模型。
角色的面部必须朝向 +Z 轴，即标准 glTF 的前方方向。如果模型朝向其他轴，姿态估计将会失败。
超过 100 MB 的文件还必须遵循以下规则：
- 最多可有 10,000,000 个面。超过此数量的文件将返回 400。Meshy 按三角形计算面数，且重复绘制的 mesh 每个副本都会计算一次。
- 不得使用 Draco 压缩。

Name
height_meters
Type
number
默认值 1.7
Description
角色的大致身高，以米为单位。Meshy 使用该值来更准确地缩放和绑定模型骨骼。负值将返回 400。
Name
texture_image_url
Type
string
⚠ 已弃用
Description
当模型自带 texture 时，请省略此参数。若不提供，Meshy 将使用 model_url 文件中内嵌的 texture，或输入任务的 texture。如果发送此参数，该图像将成为绑定骨骼后模型的唯一 texture，并且模型将失去其 PBR 贴图。
模型的 UV 展开基础颜色 texture，可以是公开 URL 或 Data URI。图像必须是 PNG 文件，最大为 20 MB。其他图像格式将返回 400。

返回内容

响应中的 result 字段保存了新建 Rigging 任务的 ID。

失败模式

Name
400 - Bad Request
Description
请求无法运行。错误消息会说明发现的具体问题。例如：
- 缺少参数：既未发送 model_url，也未发送 input_task_id。
- 模型格式无效：model_url 文件的扩展名不受支持。仅支持 .glb。
- URL 无法访问：Meshy 无法下载 model_url 文件。
- 模型文件过大：通过 http 或 https URL 提供的 model_url 文件超过 400 MB，或作为 Data URI 提供时超过 100 MB。
- 面数过多：model_url 文件超过 100 MB，且面数超过 10,000,000。请减少面数后重新发送文件。
- 模型文件无法读取：model_url 文件超过 100 MB，且 Meshy 无法读取其文件头。例如，该文件是经过 Draco 压缩的 GLB。
- 模型文件头过于复杂：model_url 文件超过 100 MB，其文件头中包含的 mesh、节点或记录过多，无法检查。请减少文件中的对象数量后重新发送。
- 图像过大：texture_image_url 图像超过 20 MB。
- texture 格式无效：texture_image_url 图像不是 PNG 文件。
- 身高无效：height_meters 为负值。
- 输入任务无效：input_task_id 未指向有效的 API 任务。
- 超出面数限制：输入模型的面数超过 320,000。请先对其运行 Remesh API，将 target_polycount 设置为 300000 或更低，然后再对模型进行 rigging。
请修正请求后重新发送。参见Errors。
Name
401 - Unauthorized
Description
API key 缺失或无效。请检查 Authorization 请求头。
Name
402 - Payment Required
Description
例如：
- 积分不足：账户没有足够的积分来完成此任务，或账户已达到积分限额。请检查您的积分余额，然后重试。
- 免费套餐：创建任务需要付费套餐。请在订阅设置中升级您的套餐，然后重试。
Name
403 - Forbidden
Description
input_task_id 是一个浮雕模型，此 endpoint 无法为其绑定骨骼。消息内容为 This model type does not support this operation。请发送其他模型。
Name
422 - Unprocessable Entity
Description
姿态估计失败。该模型可能不是有效的人形角色。请发送人形角色模型。对于 model_url，还请检查角色是否朝向 +Z 轴。
Name
429 - Too Many Requests
Description
您已超出速率限制。请稍候后重试。参见速率限制。

GET/openapi/v1/rigging/:id

获取一个 Rigging 任务

根据 ID 返回一个 Rigging 任务。

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
}

参数

Name
id
Type
path
Description
创建响应中返回的任务 ID。

返回值

Rigging 任务对象。

DELETE/openapi/v1/rigging/:id

删除一个 Rigging 任务

永久删除一个 Rigging 任务，包括其模型和数据。删除操作无法撤销。

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；当任务处于 IN_PROGRESS 状态时返回 409 Conflict。

GET/openapi/v1/rigging

列出 Rigging 任务

返回分页的 Rigging 任务列表，按最新创建时间排序。要翻页浏览列表，请使用 page_num 和 page_size。

你通过 API 创建的任务只会保留在 API 中，不会出现在 Web App 的我的资产中。如果你丢失了某个任务的 ID，可以使用此 endpoint 查找该任务。

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

流式获取 Rigging 任务

以服务器推送事件（SSE）的形式流式传输 Rigging 任务的更新。

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

    "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
path
Description
创建响应中返回的任务 ID。

以服务器推送事件形式返回的 Rigging 任务对象流。

每个事件都包含完整的任务对象，其结构与 Get endpoint 返回的相同。当任务处于 PENDING 或 IN_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": {

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

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
任务失败时的错误详情。请参阅 Errors。
Name
consumed_credits
Type
integer
Description
任务消耗的积分数量。当状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会显示此字段。对于 FAILED 的任务，该值为 0，因为 Meshy 会在任务失败时退还积分。
Name
result
Type
object
Description
输出文件的 URL。在任务成功之前，每个 URL 均为空字符串，basic_animations 为 null。
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  绑定后角色的 FBX 文件下载地址。
- Name
  rigged_character_glb_url
  Type
  string
  Description
  绑定后角色的 GLB 文件下载地址。
- Name
  basic_animations
  Type
  object (optional)
  Description
  默认行走和跑步动画的下载地址。
  Name
  walking_glb_url
  Type
  string
  Description
  带蒙皮的行走动画，GLB 文件格式。
  Name
  walking_fbx_url
  Type
  string
  Description
  带蒙皮的行走动画，FBX 文件格式。
  Name
  walking_armature_glb_url
  Type
  string
  Description
  行走动画的 armature，GLB 文件格式。
  Name
  running_glb_url
  Type
  string
  Description
  带蒙皮的跑步动画，GLB 文件格式。
  Name
  running_fbx_url
  Type
  string
  Description
  带蒙皮的跑步动画，FBX 文件格式。
  Name
  running_armature_glb_url
  Type
  string
  Description
  跑步动画的 armature，GLB 文件格式。
Name
preceding_tasks
Type
integer
Description
排在该任务之前的任务数量。该值仅在任务处于 PENDING 状态时才有意义。