Rigging API
为类人或四足 3D 模型添加骨骼(armature)并将 mesh 绑定到其上,使角色可以进行动画制作。要为已完成 rigging 的角色应用 Animation,请参阅 Animation API。
Rigging 对具有清晰四肢和身体结构的标准类人(两足)角色,以及四足动物都能很好地适用。要为动物进行 rigging,请参阅 为四足动物绑骨。
创建 Rigging 任务
为 3D 模型创建一个 Rigging 任务。任务成功后,会返回标准格式的绑定角色,并可选返回基础的行走和奔跑 Animation。
任务在后台运行。关于任务通常需要多长时间,请参见处理时间。
Rigging 不适用于以下模型:
- 未贴图的 mesh
- 既非人形也非四足动物的 asset
- 四肢和身体结构不清晰的人形 asset
Request
# 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或httpsURL 的 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 压缩。
- 最多可以有 10,000,000 个面。超过该数量的文件会返回
- Name
- animation_type
- Type
- string
- 默认值 biped
- Description
要绑定的角色种类。任何其他值都会返回
400。可用值:
biped:人形角色quadruped:四足动物。参见绑定四足动物。
- Name
- height_meters
- Type
- number
- 默认值 1.7 (biped)
- Description
模型的高度(以米为单位)。Meshy 会将绑定后的模型缩放到该高度。负值会返回
400。- Biped rig:默认为
1.7。 - Quadruped rig:如果不提供该值,或提供
0,动物会保持自身原本的大小。
- Biped rig:默认为
- 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:Mixamoue5_mannequin:Unreal Engine 5 Mannequinmax_biped:3ds Max Bipedunity_humanoid:Unity Humanoidmaya_human_ik:Maya HumanIKblender_rigify_basic_human:Blender Rigify basic humancc5_hd_neutral_base:Character Creator 5 HD neutral basedaz_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 会自动识别手指,在手指分开明显的手部上效果最佳。对于被建模为一个整体形状的手部(例如连指手套、手套或风格化手部),绑定结果中手指骨骼可能较少,并将整只手作为一个整体进行动画处理。无论哪种情况,其余骨骼结构都相同。骨骼中也可能包含额外的骨骼,例如用于头发或衣物的骨骼。手指骨骼不会改变 积分 费用。
- quadruped rig、
返回值
响应的 result 字段保存新 Rigging 任务的 ID。
失败模式
- Name
400 - Bad Request- Description
请求无法运行。错误消息会说明发现的问题。例如:
- 缺少参数:既未发送
model_url,也未发送input_task_id。 - 模型格式无效:
model_url文件的扩展名不受支持。仅支持.glb。 - URL 无法访问:Meshy 无法下载
model_url文件。 - 模型文件过大:来自
http或httpsURL 的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发送。
- Meshy 在该任务的
- 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
# 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"
}'
获取一个 Rigging 任务
根据 ID 返回一个 Rigging 任务。
Request
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=..."
}
}
}
删除一个 Rigging 任务
永久删除一个 Rigging 任务,包括其模型和数据。删除操作无法撤销。
Request
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。
列出 Rigging 任务
返回分页的 Rigging 任务列表,按最新创建时间排序。要翻页浏览列表,请使用 page_num 和 page_size。
你通过 API 创建的任务只会保留在 API 中,不会出现在 Web App 的我的资产中。如果你丢失了某个任务的 ID,可以使用此 endpoint 查找该任务。
Request
curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
流式获取 Rigging 任务
以 Server-Sent Events(SSE)的形式流式传输 Rigging 任务的更新。
Request
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时,该字段会被省略。