Animation API
为已绑定骨骼的角色应用 Animation,并列出可应用的 Animation。
创建 Animation 任务
创建一个 Animation 任务,将动画应用到你之前绑定好骨骼的角色上。该动画可以是以下任意一种:
- 来自动画库的预设动作(
action_id) - 多个预设动作合并成一个文件(
action_ids) - 你通过 Text to Motion API
生成的动作片段(motion_task_id)
你也可以对输出结果进行后处理。该任务会在后台运行。关于任务通常耗时多久,请参阅处理时间。
Request
# Animate a rigged model with required params only
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
}'
# Apply several preset actions and get one file with one clip per action
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_ids": [10, 25, 92]
}'
# Apply a generated Text to Motion clip instead of a preset action
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",
"motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
}'
# With post-processing to change FPS
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": 24
}
}'
Response
{
"result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}
参数
- Name
- rig_task_id
- Type
- string
- 必选
- Description
要为其应用动画的 Rigging 任务的 ID,来自
POST /openapi/v1/rigging。该任务的状态必须是SUCCEEDED。
请恰好发送 action_id、action_ids、motion_task_id 三者之一。
- Name
- action_id
- Type
- integer
- 必选
- Description
除非你发送了
action_ids或motion_task_id,否则必填。要应用的预设动画的 ID。完整的动画列表请参阅 Animation Library 参考 或 列出动画。该动画的
rig_type必须与骨骼匹配,否则请求会返回400。任何quadruped动画都适用于任何四足骨骼,无论其category所标注的是哪种动物。
- Name
- action_ids
- Type
- array of integers
- 必选
- Description
除非你发送了
action_id或motion_task_id,否则必填。要一次性应用的 1 到 10 个预设动画的 ID,不得重复。超过 10 个 ID,或存在重复 ID,都会返回400。有关 ID 列表,请参阅 Animation Library 参考 。Meshy 会返回一个文件,其中每个动作对应一个动画片段,这适用于游戏引擎中的状态机。Meshy 会对列表中的每个动作单独计费。参阅 Pricing。
只包含一个 ID 的列表与直接将该 ID 作为
action_id发送效果相同。若某个动画的
rig_type与骨骼不匹配,将返回400。
- Name
- motion_task_id
- Type
- string
- 必选
- Description
除非你发送了
action_id或action_ids,否则必填。Text to Motion 任务的 ID,使用其动作片段来代替预设动作。该任务的状态必须是SUCCEEDED,且骨骼必须是双足骨骼。Meshy 会将该片段重定向到已绑定骨骼的角色上。创建此任务时会复制该片段,因此即使之后 Text to Motion 任务过期或被你删除,也不会影响此任务。Meshy 会将 Text to Motion 任务的文件保留 3 天,请在此之前应用该片段。
- Name
- post_process
- Type
- object
- Description
对动画输出进行后处理。不填写则获得标准动画文件。
使用
motion_task_id时,重定向可能只会生成仅含 GLB 的动画。如果你发送了post_process但没有可用的 FBX 文件,任务会失败并返回task_error,Meshy 会退还你的积分。不发送post_process时,任务会成功,但animation_fbx_url为空。
post_process is set- Name
- operation_type
- Type
- string
- Description
要运行的操作。不填写时,Meshy 不会生成额外的文件。不在以下列表中的值会返回
400。可用的值:
change_fps:将帧率更改为fpsfbx2usdz:将动画转换为 USDZextract_armature:将 armature 导出为 FBX 文件
- Name
- fps
- Type
- integer
- 默认值 30
- Description
要更改为的帧率,可选
24、25、30或60之一。仅在operation_type为change_fps时生效。任何其他值都会返回400。
使用 action_ids 时,任务会返回一个合并文件,而不是每个动作一个文件。animation_glb_url 和 animation_fbx_url 各自指向一个文件,该文件以独立片段的形式保存了所请求的每一个动作。在该文件中:
- 片段顺序:遵循
action_ids数组中的顺序,而非 ID 的数字顺序。 - 片段名称:使用动画在动画库中的名称。这些名称与你从 Meshy web app 中将某角色的所有动画导出为一个文件时得到的名称一致。如果两个所请求的 ID 具有相同的片段名称,Meshy 会在较晚的那个名称后附加
action_id,以保持名称唯一。 - 后处理:Meshy 会将其应用于合并后的文件,而不是每个单独的片段。
返回值
响应的 result 字段保存新建 Animation 任务的 ID。
失败模式
- Name
400 - Bad Request- Description
请求无法运行。错误消息会说明发现了哪个问题。例如:
- 缺少参数:缺少
rig_task_id,或未发送action_id、action_ids、motion_task_id中的任何一个。 - 参数冲突:请求中同时包含了
action_id、action_ids、motion_task_id中的多个。请只发送一个。 - 无效的 rig 任务:
rig_task_id不是有效的任务 ID,不是一个 Rigging 任务,或指向的任务尚未成功完成。 - 无效的动作 ID:
action_id,或action_ids中的某个条目,不是有效的动画。 - 动作过多:
action_ids包含超过 10 个 ID。 - 动作重复:
action_ids中有重复的 ID。 - 动作片段任务未就绪:
motion_task_id对应的任务尚未达到SUCCEEDED状态。 - 不支持的骨骼:
motion_task_id需要双足骨骼,Meshy 会拒绝四足骨骼。 - 骨骼类型不匹配:某个动画的
rig_type与骨骼不匹配。
请修复请求后重新发送。参阅 Errors。
- 缺少参数:缺少
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如:
- 积分不足:账户没有足够的积分来执行此任务,或账户已达到积分限额。请检查你的积分 balance,然后重试。
- 免费方案:创建任务需要付费方案。请在你的subscription 设置中升级方案,然后重试。
- Name
403 - Forbidden- Description
rig_task_id对应的任务是浮雕模型,此 endpoint 无法为其添加动画。消息为This model type does not support this operation。请为其他模型绑定骨骼。
- Name
404 - Not Found- Description
Meshy 找不到请求所需的任务或文件。可能是以下情况之一:
- Meshy 在你的任务列表中找不到
rig_task_id对应的任务。请检查该 ID。 - Meshy 在
rig_task_id任务的expires_at之后已删除其文件。请重新为角色绑定骨骼。 - Meshy 找不到
motion_task_id对应的任务。请检查该 ID。 - 动作片段已过期,因为 Meshy 只会将 Text to Motion 任务的文件保留 3 天。请重新创建一个 Text to Motion 任务。
- Meshy 在你的任务列表中找不到
- Name
429 - Too Many Requests- Description
你已超出速率限制。请稍候后重试。参阅 速率限制。
获取 Animation 任务
根据 ID 返回一个 Animation 任务。
Request
curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018c425b-b2c6-727e-d333-3c1887i9h791",
"type": "animate",
"status": "SUCCEEDED",
"created_at": 1747032440896,
"progress": 100,
"started_at": 1747032441210,
"finished_at": 1747032457530,
"expires_at": 1747291657530,
"task_error": null,
"consumed_credits": 3,
"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=..."
}
}
删除 Animation 任务
永久删除一个 Animation 任务,包括其模型和数据。删除操作无法撤销。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/animations/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。
查询 Animation 任务列表
返回你的 Animation 任务的分页列表,按最新优先排序。如需翻页浏览列表,请使用 page_num 和 page_size。
通过 API 创建的任务不会出现在 Web App 的我的资产中,因此你需要通过 API 来管理它们。如果你丢失了某个任务的 ID,可以使用此 endpoint 来查找它。
Request
curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
流式传输 Animation 任务
以服务器发送事件(SSE)的形式流式传输 Animation 任务的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/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": "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: { // Example of a SUCCEEDED task stream item, with the same structure as the Animation task object
"id": "018c425b-b2c6-727e-d333-3c1887i9h791",
"type": "animate",
"status": "SUCCEEDED",
"created_at": 1747032440896,
"progress": 100,
"started_at": 1747032441210,
"finished_at": 1747032457530,
"expires_at": 1747291657530,
"task_error": null,
"consumed_credits": 3,
"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?..."
}
}
参数
- Name
- id
- Type
- path
- Description
来自创建响应的任务 ID。
返回
以服务器发送事件的形式返回 Animation 任务对象 的流。
每个事件都包含完整的任务对象,其结构与 Get endpoint 返回的结构相同。当任务处于 PENDING 或 IN_PROGRESS 状态时,其结果字段尚无值。
Animation 任务对象
Animation 任务对象描述应用于绑定骨骼角色的一个动画。它包含状态、进度,以及任务成功时的动画文件。
属性
Example Animation Task Object
{
"id": "018c425b-b2c6-727e-d333-3c1887i9h791",
"type": "animate",
"status": "SUCCEEDED",
"created_at": 1747032440896,
"progress": 100,
"started_at": 1747032441210,
"finished_at": 1747032457530,
"expires_at": 1747291657530,
"task_error": null,
"consumed_credits": 3,
"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?..."
}
}
- Name
- id
- Type
- string
- Description
任务 ID。将其视为不透明字符串,不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型,始终为
animate。
- 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 毫秒表示。
- 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
当任务状态为
SUCCEEDED时,动画文件的下载 URL。- Name
animation_glb_url- Type
- string
- Description
- GLB 格式的动画文件。对于使用
action_ids创建的任务,这一个文件会将每个请求的动作作为单独的剪辑保存其中。
- Name
animation_fbx_url- Type
- string
- Description
- FBX 格式的动画文件。对于使用
action_ids创建的任务,这一个文件会将每个请求的动作作为单独的剪辑保存其中。
- Name
processed_usdz_url- Type
- string
- Description
- 经过处理的 USDZ 格式动画文件。
- Name
processed_armature_fbx_url- Type
- string
- Description
- 经过处理的 FBX 格式 armature 文件。
- Name
processed_animation_fps_fbx_url- Type
- string
- Description
- 按更改后的帧率生成的 FBX 格式动画文件,例如使用了
change_fps操作时。
- Name
- preceding_tasks
- Type
- integer
- Description
排在此任务之前的队列中任务数量。该值仅在任务为
PENDING时才有意义。当值为0时将省略该字段。
列出动画
返回动画库中的每一个动画,按 action_id 排序。响应是完整列表,不分页,因此一次调用就能填充一个动作选择器。筛选条件可以缩小结果范围。若要获取全部动画,请将它们全部留空。
如果想在浏览同一列表的同时查看每个动作的动画预览,请参阅动画库参考。
此请求不消耗积分。
Request
curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"action_id": 4,
"name": "Attack",
"key": "Attack",
"category": "Fighting",
"sub_category": "AttackingwithWeapon",
"preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif",
"rig_type": "biped"
},
{
"action_id": 92,
"name": "Double Combo Attack",
"key": "Double_Combo_Attack",
"category": "Fighting",
"sub_category": "AttackingwithWeapon",
"preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif",
"rig_type": "biped"
}
]
参数
- Name
- search
- Type
- string
- Description
要搜索的文本。Meshy 会返回
name或key包含此文本的动画,不区分大小写。Meshy 按字面匹配文本,因此%和_不是通配符。
- Name
- category
- Type
- string
- Description
要列出的分类,须完全匹配。未知分类将返回空列表。
biped动画的分类有:WalkAndRunBodyMovementsDailyActionsFightingDancing
quadruped动画的分类是一种动物,例如dog或horse。
- Name
- sub_category
- Type
- string
- Description
要列出的子分类,须完全匹配。你可以在不带
category的情况下发送它。子分类名称在各分类之间并不唯一。例如,Transitioning同时存在于Fighting和DailyActions之下。因此在不带category的情况下,该筛选条件会匹配每个分类下的该子分类。
- Name
- action_ids
- Type
- string
- Description
要返回的动画,最多可传入 200 个以逗号分隔的
action_id值。可用它来查找特定 ID,而非逐一浏览。超过 200 个 ID 将返回400。响应会排除没有对应动画的 ID。因此你也可以用这个筛选条件来检查你存储的 ID 是否仍然可用。
组合筛选条件
Meshy 会将这些筛选条件组合应用。每一个都会缩小结果范围,因此只有当一个动画同时满足所有条件时,Meshy 才会返回它。在同一个筛选条件内,其任一值都可以匹配。例如,search 会匹配 name 或 key,而 action_ids 会匹配列表中的任意一个 ID。
因此,没有交集的组合会返回空数组,而不是错误。动作 92 是 “Double Combo Attack”,属于 Fighting 动画。例如:
?action_ids=92&category=Fighting会返回动作92。?action_ids=92&category=Dancing会返回[],因为它不是Dancing动画。?action_ids=92&search=walk会返回[],因为它的名称与walk不匹配。
若要获取任意分类下的特定动画,只需单独发送 action_ids。
返回值
一个动画对象列表。
创建 Animation 任务接受此 endpoint 返回的每一个 action_id,而此 endpoint 也会返回创建任务所接受的每一个 ID。两者都不包含已下线的动画。如果你缓存了动画库,请定期刷新它,以免已下线的 ID 仍然留在你的选择器中。
动画对象
动画对象描述动画库中的一个动画。
Example Animation Object
{
"action_id": 92,
"name": "Double Combo Attack",
"key": "Double_Combo_Attack",
"category": "Fighting",
"sub_category": "AttackingwithWeapon",
"preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif",
"rig_type": "biped"
}
- Name
- action_id
- Type
- integer
- Description
创建 Animation 任务时作为
action_id发送的值。它是唯一且稳定的,但不是连续的。已下线的动画会在编号中留下空缺,因此不要假设某个范围内的每个 ID 都是有效的。
- Name
- name
- Type
- string
- Description
该动画的显示名称。它并不唯一,因为有些动画会与另一个变体共享同一个名称。要识别某个动画,请使用
action_id或key。
- Name
- key
- Type
- string
- Description
该动画的唯一、稳定的标识字符串。当你需要一个非数字 ID 来作为自己存储的键时,可以使用它。
- Name
- category
- Type
- string
- Description
顶层分组,例如
Fighting。对于quadruped动画,它是一种动物,例如dog或horse。
- Name
- sub_category
- Type
- string
- Description
类别内的分组,例如
AttackingwithWeapon。
- Name
- preview_url
- Type
- string
- Description
该动作的动图预览 URL。你可以在自己的选择器中直接展示它。
- Name
- rig_type
- Type
- string
- Description
该动画所适用的骨骼类型,
biped或quadruped。它与 Rigging 任务的animation_type相匹配。一个 rig 只能使用与其自身类型相同的动画。