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 積分。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 網頁應用程式中將角色的所有動畫匯出為單一檔案時得到的名稱一致。如果兩個請求的 id 解析為相同的片段名稱，後一個會以其 action_id 作為後綴，以保持名稱唯一。
後處理：套用於合併後的檔案，而不是各別的片段。

使用 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、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
身份驗證失敗。請檢查你的 API key。
Name
402 - Payment Required
Description
執行此任務所需的積分不足。
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 進行管理——它們不會出現在網頁應用程式的「我的資產」中。如果你不再擁有某個任務的 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
任務的 progress（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
此任務消耗的積分數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會出現該欄位。對於 FAILED 的任務，將回傳 0（失敗時積分會被退還）。
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 是免費的——不會消耗任何積分。

參數

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