Animation API

用于发现可用 Animation 并将其应用于已绑定骨骼角色的端点。

POST/openapi/v1/animations

创建 Animation 任务

此 endpoint 允许你创建一个新任务，将动画应用于此前已完成绑骨的角色——可以是来自动画库的预设动作（action_id）、合并到单个文件中的多个预设动作（action_ids），或是你使用 Text to Motion API 生成的动作片段（motion_task_id）。支持后处理选项。

参数

  • Name
    rig_task_id
    Type
    string
    必选
    Description

    一个成功完成的绑骨任务（来自 POST /openapi/v1/rigging）的 id。此任务中的角色将被添加动画。

  • Name
    action_id
    Type
    integer
    Description

    要应用的预设动画动作的标识符。完整的可用动画列表请参见 动画库参考。action_id、action_ids 和 motion_task_id 三者中请仅提供其中一个。

  • Name
    action_ids
    Type
    array of integers
    Description

    一次性应用多个预设动画动作，返回一个包含每个动作各一段动画片段的单一文件——适用于在游戏引擎中通过状态机驱动角色。请从 动画库参考 中提供 1 到 10 个 action_id 值；id 必须唯一。每个动作消耗 3 credits。action_id、action_ids 和 motion_task_id 三者中请仅提供其中一个。

    传入只有一个元素的 action_ids 等同于将该值作为 action_id 传入。

  • Name
    motion_task_id
    Type
    string
    Description

    一个成功完成的 Text to Motion 任务的 id，用于替代预设动作。生成的动作片段会被重定向到已绑骨的角色上，并且该片段会在创建时被快照保存，因此即使源任务之后过期或被删除，也不会影响此任务。源任务的资产会保留 3 天——请在其过期前应用该片段。需要双足绑骨。action_id、action_ids 和 motion_task_id 三者中请仅提供其中一个。

  • Name
    post_process
    Type
    object
    Description

    针对动画输出的可选后处理。省略此参数即可获得标准动画文件。

仅当 post_process is set
  • Name
    operation_type
    Type
    string
    必选
    Description

    要执行的操作类型。可用值：change_fps、fbx2usdz、extract_armature。

  • Name
    fps
    Type
    integer
    默认值 30
    Description

    目标帧率。仅当 operation_type 为 change_fps 时适用。允许的值：24、25、30、60。

使用 action_ids 时，任务返回的是一个合并文件，而不是每个动作各一个文件：animation_glb_url 和 animation_fbx_url 各自指向一个单一资产，其中包含所有请求的动作，每个动作作为一个单独的片段。

  • 片段顺序：按照 action_ids 数组中的顺序，而不是 id 的数字顺序。
  • 片段名称：使用该动画在动画库中的名称，与你从 Meshy Web App 中将角色的所有动画导出为单一文件时得到的名称一致。如果两个请求的 id 解析为相同的片段名称，后一个会以其 action_id 作为后缀，以保持名称唯一。
  • 后处理：应用于合并后的文件，而不是单独的片段。

使用 motion_task_id 时，重定向可能只会生成 GLB 格式的动画。如果你请求了 post_process 而没有可用的 FBX，任务会以 task_error 失败，并自动退还你的 credits；如果没有请求 post_process，任务会成功，但 animation_fbx_url 为空。

返回值

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

失败模式

  • Name
    400 - Bad Request
    Description

    请求不可接受。常见原因：

    • 缺少参数：rig_task_id 缺失，或者 action_id、action_ids 和 motion_task_id 均未提供。
    • 参数冲突：action_id、action_ids 和 motion_task_id 中提供了不止一个——它们是互斥的。
    • 绑骨任务无效：rig_task_id 无效，或指向一个失败/不存在的任务。
    • 动作 ID 无效：action_id——或 action_ids 中的某一项——不对应任何有效的动画。
    • 动作过多：action_ids 包含超过 10 个 id。
    • 动作重复：action_ids 中包含了重复的 id。
    • 动作任务尚未就绪：motion_task_id 对应的任务尚未 SUCCEEDED。
    • 不支持的绑骨类型：motion_task_id 需要双足绑骨；四足绑骨会被拒绝。
  • Name
    401 - Unauthorized
    Description

    Authentication 失败。请检查你的 API key。

  • Name
    402 - Payment Required
    Description

    执行此任务所需的 credits 不足。

  • Name
    404 - Not Found
    Description

    未找到 rig_task_id 指定的绑骨任务，或未找到 motion_task_id 指定的动作任务，或该动作片段已过期（源任务资产仅保留 3 天）。

  • Name
    429 - Too Many Requests
    Description

    你已超出速率限制。

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"
}
GET/openapi/v1/animations/:id

获取 Animation 任务

此 endpoint 允许您通过有效的任务 id 获取一个 Animation 任务。请参阅 The Animation Task Object 以查看包含哪些属性。

参数

  • Name
    id
    Type
    path
    Description

    要获取的 Animation 任务的唯一标识符。

返回值

响应中包含 Animation Task 对象。有关详细信息，请查看 The Animation Task Object 部分。

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
}
DELETE/openapi/v1/animations/:id

删除 Animation 任务

此 endpoint 将永久删除一个 animation 任务，包括所有关联的模型和数据。此操作不可逆。

路径参数

  • Name
    id
    Type
    path
    Description

    要删除的 animation 任务的 ID。

任务状态

仍处于 PENDING 状态的任务会被删除，并退还创建时消耗的 credits。

已处于 IN_PROGRESS 状态的任务无法删除：该请求将被拒绝并返回 409 Conflict，任务将继续运行。工作进程已经开始处理的任务，其 credits 不可退还，因此在运行过程中删除它会让你既损失 credits 又失去结果。请等待其进入 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。

处于终结状态（SUCCEEDED、FAILED 或 CANCELED）的任务在删除时 不会退款。

返回值

成功时返回 200 OK；当任务处于 IN_PROGRESS 状态时返回 409 Conflict。

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 is left 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."
}
GET/openapi/v1/animations

获取 Animation 任务列表

返回调用者的 Animation 任务的分页列表，按最新排序。通过 page_num 和 page_size 进行标准分页。

请注意，通过 API 创建的任务由 API 进行管理——它们不会出现在 Web App 的“我的资产”中。如果你不再拥有某个任务的 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 任务

此 endpoint 通过 Server-Sent Events (SSE) 流式传输 Animation 任务的实时更新。

参数

  • Name
    id
    Type
    path
    Description

    要进行流式传输的 Animation 任务的唯一标识符。

返回

以 Server-Sent Events 的形式返回一个 The Animation Task Objects 流。

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

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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, mirroring The Animation Task Object structure
  "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
}

Animation 任务对象

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

属性

  • Name
    id
    Type
    string
    Description

    任务的唯一标识符。

  • Name
    type
    Type
    string
    Description

    Animation 任务的类型。其值为 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

    任务创建时的时间戳（自纪元起的毫秒数）。

    timestamp 表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。 例如，2023 年 9 月 1 日星期五格林尼治标准时间中午 12:00:00 表示为 1693569600000。这适用于 Meshy API 中的所有 timestamp。

  • 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

    失败任务的错误详情。有关完整的 task_error 对象参考，请参阅 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    此任务消耗的 credits 数量。当任务状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会出现该字段。对于 FAILED 的任务，将返回 0（失败时 credits 会被退还）。

  • Name
    result
    Type
    object
    Description

    如果任务状态为 SUCCEEDED，则包含输出的动画 URL。

    • Name
      animation_glb_url
      Type
      string
      Description
      GLB 格式动画的可下载 URL。对于使用 action_ids 创建的任务，这个单一文件将每个请求的动作都作为单独的片段包含在内。
    • Name
      animation_fbx_url
      Type
      string
      Description
      FBX 格式动画的可下载 URL。对于使用 action_ids 创建的任务，这个单一文件将每个请求的动作都作为单独的片段包含在内。
    • Name
      processed_usdz_url
      Type
      string
      Description
      USDZ 格式的已处理动画的可下载 URL。
    • Name
      processed_armature_fbx_url
      Type
      string
      Description
      FBX 格式的已处理 armature 的可下载 URL。
    • Name
      processed_animation_fps_fbx_url
      Type
      string
      Description
      FBX 格式的已更改 FPS 的动画的可下载 URL（例如，如果使用了 change_fps 操作）。
  • Name
    preceding_tasks
    Type
    integer
    Description

    队列中排在前面的任务数量。仅在状态为 PENDING 时有意义。

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
}
GET/openapi/v1/animations/library

List Animations

返回动画库中的每一个动画，按 action_id 排序。响应是一个完整列表而非分页结果，因此一次调用即可填充一个动作选择器。筛选条件会缩小结果范围；全部省略即可获取所有动画。

如果想通过肉眼浏览同一个目录，并查看每个动作的动画预览，请参阅 Animation Library 参考文档。

此 endpoint 是免费的——不消耗任何 credits。

参数

  • Name
    search
    Type
    string
    Description

    对 name 或 key 进行不区分大小写的子字符串匹配。按字面匹配，因此 % 和 _ 是普通字符而非通配符。

  • Name
    category
    Type
    string
    Description

    与 category 精确匹配。

    可用值：

    • WalkAndRun
    • BodyMovements
    • DailyActions
    • Fighting
    • Dancing
  • Name
    sub_category
    Type
    string
    Description

    与 sub_category 精确匹配。可单独使用——子分类名称在各分类之间并不唯一（Transitioning 同时出现在 Fighting 和 DailyActions 下），因此若不指定 category，该筛选条件会匹配该子分类出现的任意位置。

  • Name
    action_ids
    Type
    string
    Description

    以逗号分隔的 action_id 值列表，用于解析特定 id 而非浏览。最多接受 200 个 id。任何动画都不具有的 id 只会在响应中缺失，因此你也可以用它来检查你已存储的 id 是否仍然可用。

组合筛选条件

筛选条件是共同作用的——每一个都会进一步缩小结果范围，因此只有同时满足所有条件的动画才会被返回。在单个筛选条件内，多个值以“任一匹配”的方式生效：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。

返回值

返回一个由 The Animation Objects 组成的列表。

此处返回的每一个 action_id 都可被上面的 Create an Animation Task 接受，且它所接受的每一个 id 也都会在此处返回。已停用的动画在两者中都不会出现。如果你缓存了该库，请定期刷新，以免已停用的 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"
  }
]

The Animation Object

  • Name
    action_id
    Type
    integer
    Description

    创建动画任务时作为 action_id 传入的值。该值唯一且稳定，但并不连续——已废弃的动画会在编号中留下空缺，因此不要假设某个 id 区间都是有效的。

  • Name
    name
    Type
    string
    Description

    便于展示的可读性标签。它并不唯一：有些动画会与另一个变体共用同一个名称，因此请使用 action_id 或 key 作为身份标识。

  • Name
    key
    Type
    string
    Description

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

  • Name
    category
    Type
    string
    Description

    顶级分组，例如 Fighting。

  • Name
    sub_category
    Type
    string
    Description

    类别内的子分组，例如 AttackingwithWeapon。

  • Name
    preview_url
    Type
    string
    Description

    用于预览该动作的动图 URL，可直接在你自己的选择器中渲染展示。

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