lowpoly 将于 2026年10月30日 下线。 meshy-7 作为 3D 生成模型将于 2026年12月31日 下线;作为贴图模型仍可使用。 请在这些日期前切换模型,以免请求报错。 查看所有弃用信息

Rigging API

为类人或四足 3D 模型添加骨骼(armature)并将 mesh 绑定到其上,使角色可以进行动画制作。要为已完成 rigging 的角色应用 Animation,请参阅 Animation API。

Rigging 对具有清晰四肢和身体结构的标准类人(两足)角色,以及四足动物都能很好地适用。要为动物进行 rigging,请参阅 为四足动物绑骨。


POST/openapi/v1/rigging

创建 Rigging 任务

为 3D 模型创建一个 Rigging 任务。任务成功后,会返回标准格式的绑定角色,并可选返回基础的行走和奔跑 Animation。

任务在后台运行。关于任务通常需要多长时间,请参见处理时间。

Rigging 不适用于以下模型:

  • 未贴图的 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,否则必填。你想绑定其模型的任务的 ID。Meshy 支持带贴图的人形模型和四足动物。

    模型最多可以有 380,000 个三角形(一个四边面算作 2 个),超过该数量的模型会返回 400。要保持在限制以内,可先用 target_polycount 为 300000 或更小(若 topology: quad 则为 150000 或更小)运行 Remesh API。

  • Name
    model_url
    Type
    string
    必选
    Description

    除非发送 input_task_id,否则必填。要绑定的模型,作为公开 URL 或 data URI。如果两者都发送,Meshy 会使用 input_task_id。

    模型必须是来自 http 或 https URL 的 GLB(.glb)文件,大小不超过 400 MB;若作为 data URI,则不超过 100 MB。Rigging 支持带贴图的人形模型和四足动物。

    模型最多可以有 380,000 个三角形(一个四边面算作 2 个),超过该数量的模型会返回 400。要保持在限制以内,可先用 target_polycount 为 300000 或更小(若 topology: quad 则为 150000 或更小)运行 Remesh API。

    角色的面部必须朝向 +Z 轴,即标准的 glTF 前方方向。如果模型朝向其他轴,姿态估计将会失败。

    超过 100 MB 的文件还必须遵循以下规则:

    • 最多可以有 10,000,000 个面。超过该数量的文件会返回 400。Meshy 将面计为三角形,被多次绘制的 mesh 每个副本计一次。
    • 不得使用 Draco 压缩。
  • Name
    animation_type
    Type
    string
    默认值 biped
    Description

    要绑定的角色种类。任何其他值都会返回 400。

    可用值:

  • Name
    height_meters
    Type
    number
    默认值 1.7 (biped)
    Description

    模型的高度(以米为单位)。Meshy 会将绑定后的模型缩放到该高度。负值会返回 400。

    • Biped rig:默认为 1.7。
    • Quadruped rig:如果不提供该值,或提供 0,动物会保持自身原本的大小。
  • Name
    texture_image_url
    Type
    string
    ⚠ 已弃用
    Description

    当模型自带 texture 时,请省略此参数。若不提供,Meshy 会使用 model_url 文件中嵌入的 texture,或输入任务的 texture。如果你发送了此参数,该图像将成为绑定模型的唯一 texture,模型将失去其 PBR 贴图。

    模型经过 UV 展开的基础颜色 texture,可以是公开 URL 或 data URI。图像必须是 PNG 文件,大小不超过 20 MB。其他图像格式会返回 400。

  • Name
    skeleton_template
    Type
    string
    默认值 meshyrig
    Description

    绑定角色所使用的骨骼,它决定骨骼名称及层级结构。请选择你的引擎或工具所需的骨骼类型。

    可用值:

    • meshyrig:Meshy 自有骨骼
    • mixamo:Mixamo
    • ue5_mannequin:Unreal Engine 5 Mannequin
    • max_biped:3ds Max Biped
    • unity_humanoid:Unity Humanoid
    • maya_human_ik:Maya HumanIK
    • blender_rigify_basic_human:Blender Rigify basic human
    • cc5_hd_neutral_base:Character Creator 5 HD neutral base
    • daz_genesis9:DAZ Genesis 9

    任何其他值都会返回 400。仅适用于 biped rig。

    如果值不是 meshyrig,或 include_fingers 设为 true,生成的文件将以米为单位,并使用该骨骼对应的骨骼结构,而不是默认的以厘米为单位的 24 骨骼 meshyrig 文件。如果 Meshy 无法在该骨骼上绑定某个模型,任务会失败。此时可改用 meshyrig 并将 include_fingers 设为 false,或改用其他值重试。

    这些文件中的库动画片段名称与默认 meshyrig 文件中的名称相同,例如 Armature|walking_man|baselayer。在每个 rig 中,Text to Motion 片段都命名为 retarget_clip。FBX 文件包含末端骨骼。少数末端骨骼(例如 headfront)会保留其原始名称。

    由该 rig 生成的 Animation 任务使用相同的骨骼。

  • Name
    include_fingers
    Type
    boolean
    默认值 false
    Description

    是否为角色的手部添加手指骨骼。仅适用于 biped rig。使用 meshyrig 时,手指骨骼使用 Mixamo 名称,例如 LeftHandThumb1。

    当设为 true 时,以下请求会返回错误,且 Meshy 不会为其计费:

    • quadruped rig、texture_image_url,或其模型具有四边面 topology 的 input_task_id,都会返回 400。
    • 只有不带手指骨骼才能绑定的模型会返回 422。
    • 如果 Meshy 无法为角色的手部绑定手指骨骼,任务会失败。请重试,或将 include_fingers 设为 false。

    Meshy 会自动识别手指,在手指分开明显的手部上效果最佳。对于被建模为一个整体形状的手部(例如连指手套、手套或风格化手部),绑定结果中手指骨骼可能较少,并将整只手作为一个整体进行动画处理。无论哪种情况,其余骨骼结构都相同。骨骼中也可能包含额外的骨骼,例如用于头发或衣物的骨骼。手指骨骼不会改变 积分 费用。

返回值

响应的 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 为负值。
    • 骨骼模板无效:skeleton_template 不是可用值之一,或与 quadruped rig 一起发送。
    • 不支持手指骨骼:include_fingers 为 true,且使用了 quadruped rig、texture_image_url,或其模型具有四边面 topology 的 input_task_id。
    • 输入任务无效:input_task_id 未指向有效的 API 任务。
    • 输入任务尚未就绪:input_task_id 任务尚未达到 SUCCEEDED 状态。请等待其成功后重试。
    • 超出面数限制:输入模型的三角形数量超过 380,000(一个四边面算作 2 个)。在绑定模型之前,请先用 target_polycount 为 300000 或更小(若 topology: quad 则为 150000 或更小)运行 Remesh API。

    修正请求后重新发送。参见 Errors。

  • Name
    401 - Unauthorized
    Description

    API key 缺失或无效。请检查 Authorization 头。

  • Name
    402 - Payment Required
    Description

    例如:

    • 积分不足:账户没有足够的 积分 来完成此任务,或账户已达到 积分 限额。请检查你的 积分 balance,然后重试。
    • 免费方案:创建任务需要付费方案。请在你的订阅设置中升级方案,然后重试。
  • Name
    403 - Forbidden
    Description

    input_task_id 是一个浮雕模型,此 endpoint 无法为其绑定骨骼。消息为 This model type does not support this operation。请发送其他模型。

  • Name
    404 - Not Found
    Description

    Meshy 找不到 input_task_id 任务的文件。以下情况之一适用:

    • Meshy 在该任务的 expires_at 之后删除了其文件。请重新创建该任务,然后发送该新任务的 ID。
    • 该任务缺少 rigging 所需的文件,例如预览图像,例如一个 Convert 任务。请对其来源任务进行绑定,或将模型作为 model_url 发送。
  • Name
    422 - Unprocessable Entity
    Description

    例如:

    • 姿态估计失败:模型可能不是有效的人形角色。请发送人形角色的模型。对于 model_url,还需检查角色是否朝向 +Z 轴。
    • 骨骼模板不可用:Meshy 只能在 meshyrig 骨骼上绑定此模型。请省略 skeleton_template,或将其设为 meshyrig。Meshy 不会为此请求计费。
    • 手指骨骼不可用:Meshy 只能在不带手指骨骼的 meshyrig 上绑定此模型。请省略 include_fingers 和 skeleton_template。Meshy 不会为此请求计费。
  • Name
    429 - Too Many Requests
    Description

    你已超出速率限制。请稍候后重试。参见速率限制。

  • Name
    503 - Service Unavailable
    Description

    Meshy 未能完成对模型姿态的分析。请重试该请求。


给四足动物绑定骨骼

要为四足动物进行 rigging,请发送设置为 quadruped 的 animation_type。

四足骨骼与双足骨骼的区别如下:

  • basic_animations 包含该动物的行走和奔跑动画。如果 Meshy 无法生成其中某一个动画,其 URL 将为空字符串,任务仍会成功。walking_armature_glb_url 和 running_armature_glb_url 是该 rig 的骨骼,不包含动画。
  • height_meters 的默认值不是 1.7。参见创建 Rigging 任务。
  • 发送 skeleton_template,或将 include_fingers 设置为 true,将返回 400。
  • 如果 Meshy 无法将该模型绑定为四足动物骨骼,任务将失败。

四足骨骼的费用与双足骨骼相同。参见 Pricing。

要为已绑定骨骼的动物添加动画,请应用 rig_type 为 quadruped 的库动画,作为 action_id 或 action_ids。参见 Animation。

Request

POST
/openapi/v1/rigging
# Rig a four-legged animal
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",
    "animation_type": "quadruped"
  }'

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

返回

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 任务

以 Server-Sent Events(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": 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 形式返回的 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": 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

    任务失败时的错误详情。除非状态为 FAILED,否则该值为 null。请参阅 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 状态时有意义。当值为 0 时,该字段会被省略。