Animation API

用於探索可用的動畫，並將其套用至已完成骨骼綁定角色的端點。

POST/openapi/v1/animations

建立動畫任務

此 endpoint 允許您建立一個新任務，將動畫套用到先前已完成骨骼綁定的角色上——可以是動畫庫中的預設動作（action_id），也可以是您使用 Text to Motion API 生成的動作片段（motion_task_id）。支援後處理選項。

參數

Name
rig_task_id
Type
string
必選
Description
成功完成的骨骼綁定任務的 id（來自 POST /openapi/v1/rigging）。此任務中的角色將被套用動畫。
Name
action_id
Type
integer
Description
要套用的預設動畫動作的識別碼。有關可用動畫的完整清單，請參閱動畫庫參考。action_id 和 motion_task_id 二者必須提供且僅提供一個。
Name
motion_task_id
Type
string
Description
要套用的、成功完成的 Text to Motion 任務的 id，用於代替預設動作。生成的動作片段會被重定向到已完成骨骼綁定的角色上，並且該片段會在建立時被快照儲存，因此即使來源任務之後過期或被刪除，也不會影響此任務。來源任務的 asset 保留 3 天——請在其過期前套用該片段。需要雙足骨骼綁定。action_id 和 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。

使用 motion_task_id 時，重定向可能只會生成 GLB 格式的動畫。如果您請求了 post_process 但沒有可用的 FBX，任務將以 task_error 失敗，您的積分將自動退還；如果未請求 post_process，任務將成功，且 animation_fbx_url 為空。

返回值

回應中的 result 屬性包含新建立的動畫任務的 id。

失敗模式

Name
400 - Bad Request
Description
請求不可接受。常見原因：
- 缺少參數：缺少 rig_task_id，或既未提供 action_id 也未提供 motion_task_id。
- 參數衝突：同時提供了 action_id 和 motion_task_id——二者互斥。
- 骨骼綁定任務無效：rig_task_id 無效，或指向一個失敗/不存在的任務。
- 動作 ID 無效：action_id 未對應任何有效動畫。
- 動作任務尚未就緒：motion_task_id 對應的任務尚未 SUCCEEDED。
- 不支援的骨骼綁定類型：motion_task_id 需要雙足骨骼綁定；四足骨骼綁定將被拒絕。
Name
401 - Unauthorized
Description
身份驗證失敗。請檢查您的 API key。
Name
402 - Payment Required
Description
積分不足，無法執行此任務。
Name
404 - Not Found
Description
未找到 rig_task_id 指定的骨骼綁定任務，或未找到 motion_task_id 指定的動作任務，或該動作片段已過期（來源任務的 asset 保留 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 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。

回傳值

成功時回傳 200 OK。

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

// Returns 200 Ok on success.

GET/openapi/v1/animations

取得 Animation 任務清單

傳回呼叫者的 Animation 任務的分頁清單，依最新排序。透過 page_num 和 page_size 進行標準分頁。

請注意，透過 API 建立的任務由 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 任務

此 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
任務建立時的時間戳（自紀元以來的毫秒數）。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。例如，2023 年 9 月 1 日星期五格林威治標準時間中午 12:00:00 表示為 1693569600000。這適用於 Meshy API 中的所有時間戳。
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 物件參考，請參閱錯誤。
Name
consumed_credits
Type
integer
Description
此任務消耗的積分數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會顯示此欄位。對於 FAILED 任務會回傳 0（失敗時會退還積分）。
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 時有意義。

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
}