lowpoly 将于 2026年10月30日 下线。 请在这些日期前切换模型，以免请求报错。 查看所有弃用信息

Animation API

为已绑定骨骼的角色应用 Animation，并列出可应用的 Animation。

POST/openapi/v1/animations

创建 Animation 任务

创建一个 Animation 任务，将动画应用到你之前绑定骨骼的角色上。动画可以是以下之一：

  • 来自动画库的预设动作（action_id）
  • 合并到一个文件中的多个预设动作（action_ids）
  • 你使用 Text to Motion API 生成的动作片段（motion_task_id）

你也可以对输出进行后处理。任务在后台运行。有关任务通常耗时多久，请参阅处理时间。

Request

POST
/openapi/v1/animations
# 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。完整的动画列表请参阅 动画库参考 或 列出动画。

  • Name
    action_ids
    Type
    array of integers
    必选
    Description

    除非你发送 action_id 或 motion_task_id，否则此项必填。要一次性应用的 1 到 10 个预设动画的 ID，不能重复。超过 10 个 ID，或存在重复 ID，将返回 400。有关 ID 列表，请参阅 动画库参考。

    Meshy 会为每个动作返回一个包含一个动画片段的文件，这适用于游戏引擎中的状态机。Meshy 会对列表中的每个动作单独计费。请参阅 Pricing。

    只包含一个 ID 的列表与将该 ID 作为 action_id 发送的效果相同。

  • Name
    motion_task_id
    Type
    string
    必选
    Description

    除非你发送 action_id 或 action_ids，否则此项必填。要应用其片段以代替预设动作的 Text to Motion 任务的 ID。该任务的状态必须为 SUCCEEDED，且 rig 必须是双足的。

    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：将帧率更改为 fps
    • fbx2usdz：将动画转换为 USDZ
    • extract_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 状态。
    • 不支持的 rig：motion_task_id 需要双足 rig，Meshy 会拒绝四足 rig。

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

  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    例如：

    • 积分不足：账户没有足够的积分来完成此任务，或账户已达到积分限额。请检查你的积分余额，然后重试。
    • 免费计划：创建任务需要付费计划。请在你的 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 任务。
  • Name
    429 - Too Many Requests
    Description

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

GET/openapi/v1/animations/:id

获取 Animation 任务

根据 ID 返回一个 Animation 任务。

Request

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

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

    "message": ""

  },

  "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=..."
  },
  "preceding_tasks": 0
}

参数

  • Name
    id
    Type
    path
    Description

    创建响应中的任务 ID。

返回值

Animation 任务对象。

DELETE/openapi/v1/animations/:id

删除 Animation 任务

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

Request

DELETE
/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579
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。

GET/openapi/v1/animations

查询 Animation 任务列表

返回你的 Animation 任务的分页列表，按最新优先排序。如需翻页浏览列表，请使用 page_num 和 page_size。

通过 API 创建的任务不会出现在 Web App 的我的资产中，因此你需要通过 API 来管理它们。如果你丢失了某个任务的 ID，可以使用此 endpoint 来查找它。

Request

GET
/openapi/v1/animations
curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/animations/:id/stream

流式获取 Animation 任务

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

Request

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

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

    "message": ""

  },

  "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?..."
  },
  "preceding_tasks": 0
}

参数

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

    "message": ""

  },

  "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?..."
  },
  "preceding_tasks": 0
}
  • 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

    任务失败时的错误详情。参见错误。

  • Name
    consumed_credits
    Type
    integer
    Description

    任务消耗的积分数量。当状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时存在。对于 FAILED 的任务，此值为 0，因为 Meshy 会在任务失败时退还积分。

  • Name
    result
    Type
    object
    Description

    动画文件的下载链接，仅在任务状态为 SUCCEEDED 时提供。

    • 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
      处理后的 armature，以 FBX 文件形式提供。
    • Name
      processed_animation_fps_fbx_url
      Type
      string
      Description
      更改帧率后的动画，以 FBX 文件形式提供，例如当你使用了 change_fps 操作时。
  • Name
    preceding_tasks
    Type
    integer
    Description

    排在此任务之前的队列中任务数量。该值仅在任务处于 PENDING 状态时才有意义。

GET/openapi/v1/animations/library

获取动画列表

返回动画库中的所有动画，按 action_id 排序。响应结果是完整列表，不分页，因此一次调用即可填充整个动作选择器。筛选条件可以缩小结果范围。若要获取全部动画，则不要传入任何筛选条件。

如需浏览同一列表并查看每个动作的动画预览，请参阅动画库参考。

此请求不消耗积分。

Request

GET
/openapi/v1/animations/library
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"
  },
  {
    "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"
  }
]

参数

  • Name
    search
    Type
    string
    Description

    要搜索的文本。Meshy 会返回 name 或 key 中包含该文本的动画，不区分大小写。Meshy 会按字面匹配该文本，因此 % 和 _ 不是通配符。

  • Name
    category
    Type
    string
    Description

    要列出的类别，需精确匹配。未知类别会返回空列表。

    可用值：

    • WalkAndRun
    • BodyMovements
    • DailyActions
    • Fighting
    • Dancing
  • 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。

返回值

一个动画对象列表。

创建动画任务接受此 endpoint 返回的所有 action_id，而此 endpoint 也会返回创建任务所接受的所有 ID。两者都不包含已停用的动画。如果你缓存了动画库，请定期刷新，以免已停用的 ID 仍留在你的选择器中。

The animation object

一个 animation 对象描述库中的一个动画。

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"
}
  • Name
    action_id
    Type
    integer
    Description

    创建 Animation 任务时作为 action_id 发送的值。它是唯一且稳定的，但并不连续。已下线的动画会在编号中留下空隙，因此不要假设某个范围内的每个 ID 都是有效的。

  • Name
    name
    Type
    string
    Description

    动画的显示名称。它并不唯一，因为部分动画会与其他变体共享同一个名称。要识别某个动画，请使用 action_id 或 key。

  • Name
    key
    Type
    string
    Description

    该动画唯一且稳定的 slug。当你需要一个非数字 ID 来为自己的存储建立键值时可以使用它。

  • Name
    category
    Type
    string
    Description

    顶层分组，例如 Fighting。

  • Name
    sub_category
    Type
    string
    Description

    分类下的子分组，例如 AttackingwithWeapon。

  • Name
    preview_url
    Type
    string
    Description

    该动作的 GIF 预览动图地址。你可以在自己的选择器中直接展示它。