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

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。完整的动画列表请参阅 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:将帧率更改为 fps
    • fbx2usdz:将动画转换为 USDZ
    • extract_armature:将 armature 导出为 FBX 文件
  • Name
    fps
    Type
    integer
    默认值 30
    Description

    要更改为的帧率,可选 24、25、30 或 60 之一。仅在 operation_type 为 change_fps 时生效。任何其他值都会返回 400。

返回值

响应的 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 任务。
  • 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": 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=..."
  }
}

参数

  • 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": 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 时将省略该字段。


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",
    "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 动画的分类有:

    • WalkAndRun
    • BodyMovements
    • DailyActions
    • Fighting
    • Dancing

    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。

返回值

一个动画对象列表。


动画对象

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

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 只能使用与其自身类型相同的动画。