动画 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
      必选
      Description

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

    • Name
      fps
      Type
      integer
      默认值 30
      Description

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

返回

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

失败模式

  • Name
    400 - Bad Request
    Description

    请求不合法。常见原因：

    • 缺少参数：rig_task_id 或 action_id 未提供。
    • 绑定任务无效：rig_task_id 无效或引用了一个失败/不存在的任务。
    • 动作 ID 无效：action_id 不对应任何有效的动画。
  • Name
    401 - Unauthorized
    Description

    认证失败。请检查您的 API 密钥。

  • Name
    402 - Payment Required
    Description

    积分不足，无法执行此任务。

  • Name
    404 - Not Found
    Description

    未找到 rig_task_id 指定的绑定任务。

  • Name
    429 - Too Many Requests
    Description

    您已超出请求频率限制。

请求

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

# 使用后处理更改帧率
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

获取动画任务

此接口允许您通过有效的任务 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",
  "type": "animate",
  "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
}
DELETE/openapi/v1/animations/:id

删除动画任务

此端点可永久删除一个动画任务，包括所有相关的模型和数据。此操作不可逆。

路径参数

  • Name
    id
    Type
    path
    Description

    要删除的动画任务的ID。

返回值

成功则返回 200 OK。

请求

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

响应

// 成功则返回 200 Ok。
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",
  "type": "animate",
  "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
    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

    任务创建时的时间戳（自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

    如果任务失败则为错误对象，否则为包含空消息字符串的对象。详情请参阅 Errors。

    • 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",
  "type": "animate",
  "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
}