自动绑定和动画 API

自动绑定和动画 API 允许您通过编程方式对 3D 模型进行骨骼绑定，并为其应用动画，利用 Meshy 的后端能力。本节提供了集成这些功能所需的详细信息。

请注意，目前编程绑定与动画仅适用于标准人形（双足）资产，且需具备清晰的四肢和身体结构。

自动绑定 API

用于提交和获取角色绑定任务的接口。绑定过程包括创建内部骨架（骨架结构）并将模型的网格（皮肤）绑定到骨架上，使其可以进行动画处理。

POST/openapi/v1/rigging

创建绑定任务

该接口允许您为指定的 3D 模型创建新的绑定任务。任务完成后，将返回标准格式的已绑定角色，并可选提供基础的行走/奔跑动画。

当前，自动绑定不适用于以下模型：

无贴图网格
非人形资产
人形但四肢和身体结构不清晰的资产

参数

必填属性

Name
input_task_id
Type
string
Description
需要进行绑定的输入任务 ID。如果未提供 model_url，则必填。目前仅支持带贴图的人形模型。
input_task_id 和 model_url 只能二选一作为绑定输入。
Name
model_url
Type
string
Description
请通过公开可访问的 URL 或 Data URI 提供需要绑定的 3D 模型。目前仅支持带贴图的人形 GLB 文件（.glb 格式）。如果未提供 input_task_id，则必填。
input_task_id 和 model_url 只能二选一作为绑定输入。

可选属性

Name
height_meters
Type
number
Description
角色模型的大致身高（单位：米）。有助于缩放和绑定精度。必须为正数。默认值：1.7。
Name
texture_image_url
Type
string
Description
模型的基础色贴图图片。需为公开可访问的 URL 或 Data URI。目前仅支持 .png 格式。

返回值

响应的 result 字段包含新建绑定任务的任务 id。

请求

POST

/openapi/v1/rigging

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",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {
    "message": ""
  },
  "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=...",
    "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
}

GET/openapi/v1/rigging/:id/stream

流式获取绑定任务

此端点使用服务器发送事件(SSE)流式传输绑定任务的实时更新。

参数

Name
id
Type
path
Description
要流式传输的绑定任务的唯一标识符。

以服务器发送事件的形式返回绑定任务对象的流。

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

响应流

// 错误事件示例
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// 消息事件示例说明任务进度
// 对于PENDING或IN_PROGRESS状态的任务，响应流不会包含所有字段
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",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {
    "message": ""
  },
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "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
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
任务创建时的时间戳（自1970年1月1日UTC以来的毫秒数）。
时间戳表示自1970年1月1日UTC以来经过的毫秒数，遵循 RFC 3339标准。例如，2023年9月1日星期五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
任务失败时的错误对象，否则为包含空消息字符串的对象。
- Name
  message
  Type
  string
  Description
  详细错误信息。任务成功时为空。
Name
result
Type
object
Description
任务SUCCEEDED时包含输出资源URL，否则为null。
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  已绑定角色的FBX格式可下载URL。
- Name
  basic_animations
  Type
  object (optional)
  Description
  包含默认动画的URL。（例如，如果generate_basic_animations默认为true或默认启用）。
  Name
  walking_glb_url
  Type
  string
  Description
  行走动画的GLB格式可下载URL（带蒙皮）。
  Name
  walking_fbx_url
  Type
  string
  Description
  行走动画的FBX格式可下载URL（带蒙皮）。
  Name
  walking_armature_glb_url
  Type
  string
  Description
  行走动画骨架的GLB格式可下载URL。
  Name
  running_glb_url
  Type
  string
  Description
  跑步动画的GLB格式可下载URL（带蒙皮）。
  Name
  running_fbx_url
  Type
  string
  Description
  跑步动画的FBX格式可下载URL（带蒙皮）。
  Name
  running_armature_glb_url
  Type
  string
  Description
  跑步动画骨架的GLB格式可下载URL。
Name
preceding_tasks
Type
integer
Description
队列中前置任务的数量。仅在状态为PENDING时有意义。

绑定任务对象示例

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {
    "message": ""
  },
  "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=...",
    "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
}

动画 API

用于发现可用动画并将其应用到已绑定角色的端点。

POST/openapi/v1/animations

创建动画任务

此端点允许您创建一个新任务，将特定的动画动作应用到之前已绑定的角色上。包含后处理选项。

参数

必需属性

Name
rig_task_id
Type
string
Description
成功完成的绑定任务的id（来自POST /openapi/v1/rigging）。将对此任务中的角色进行动画处理。
Name
action_id
Type
integer
Description
要应用的动画动作的标识符。查看动画库参考获取可用动画的完整列表。

可选属性

Name
post_process
Type
object
Description
动画文件后处理参数。
- Name
  operation_type
  Type
  string (required)
  Description
  要执行的操作类型。必须是以下之一：
  
  change_fps（调整帧率）
  
  fbx2usdz（将FBX转换为USDZ）
  
  extract_armature（提取骨架）
- Name
  fps
  Type
  integer (optional)
  Description
  目标帧率。默认值：30。仅在operation_type为change_fps时适用。允许的值：24、25、30、60。

响应的result属性包含新创建的动画任务的id。

请求

POST

/openapi/v1/animations

curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 60
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

GET/openapi/v1/animations/:id

获取动画任务

此接口允许您通过有效的任务 id 获取动画任务。请参考动画任务对象查看包含的属性。

参数

Name
id
Type
path
Description
要获取的动画任务的唯一标识符。

响应包含动画任务对象。详情请查看动画任务对象部分。

请求

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

响应

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {
    "message": ""
  },
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

GET/openapi/v1/animations/:id/stream

流式获取动画任务

此接口使用服务器发送事件(SSE)为动画任务提供实时更新流。

参数

Name
id
Type
path
Description
要流式获取的动画任务的唯一标识符。

以服务器发送事件的形式返回动画任务对象的流。

对于PENDING或IN_PROGRESS状态的任务，响应流将只包含必要的progress和status字段。

请求

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream 
-H "Authorization: Bearer ${YOUR_API_KEY}"

响应流

// 错误事件示例
event: error
data: {
  "status_code": 404,
  "message": "任务未找到"
}

// 消息事件示例展示了任务进度
// 对于PENDING或IN_PROGRESS状态的任务，响应流不会包含所有字段
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // SUCCEEDED任务流项目的示例，反映了动画任务对象的结构
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {
    "message": ""
  },
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

动画任务对象

动画任务对象表示将动画应用到已绑定骨骼的角色上的工作单元。

属性

Name
id
Type
string
Description
任务的唯一标识符。
Name
status
Type
string
Description
任务状态。可能的值：PENDING（等待中）、IN_PROGRESS（进行中）、SUCCEEDED（成功）、FAILED（失败）、CANCELED（已取消）。
Name
progress
Type
integer
Description
任务进度（0-100）。
Name
created_at
Type
timestamp
Description
任务创建时的时间戳（自1970年1月1日UTC以来的毫秒数）。
时间戳表示自1970年1月1日UTC以来经过的毫秒数，遵循 RFC 3339标准。例如，2023年9月1日星期五下午12:00:00 GMT表示为1693569600000。这适用于 Meshy API中的所有时间戳。
Name
started_at
Type
timestamp
Description
任务开始处理时的时间戳（自1970年1月1日UTC以来的毫秒数）。如果未开始则为0。
Name
finished_at
Type
timestamp
Description
任务完成时的时间戳（自1970年1月1日UTC以来的毫秒数）。如果未完成则为0。
Name
expires_at
Type
timestamp
Description
任务结果资源过期时的时间戳（自1970年1月1日UTC以来的毫秒数）。
Name
task_error
Type
object
Description
如果任务失败则为错误对象，否则为包含空消息字符串的对象。
- Name
  message
  Type
  string
  Description
  详细的错误信息。如果任务成功则为空。
Name
result
Type
object
Description
如果任务SUCCEEDED（成功），则包含输出动画的URL。
- Name
  animation_glb_url
  Type
  string
  Description
  GLB格式动画的可下载URL。
- Name
  animation_fbx_url
  Type
  string
  Description
  FBX格式动画的可下载URL。
- Name
  processed_usdz_url
  Type
  string
  Description
  USDZ格式处理后动画的可下载URL。
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  处理后骨骼的FBX格式可下载URL。
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  更改FPS后动画的FBX格式可下载URL（例如，如果使用了change_fps操作）。
Name
preceding_tasks
Type
integer
Description
队列中前置任务的数量。仅在状态为PENDING（等待中）时有意义。

动画任务对象示例

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {
    "message": ""
  },
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}