Animation API

用於探索可用的 Animation，並將其套用至具有 rig 的角色模型的端點。

POST/openapi/v1/animations

Create an Animation Task

此 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 網頁應用程式將角色的所有動畫匯出為單一檔案時得到的名稱一致。如果兩個請求的 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
身份驗證失敗。請檢查你的 API 金鑰。
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，任務會繼續執行。對於 worker 已經開始處理的任務，其 credits 不可退還，因此在執行過程中刪除它會使你同時失去 credits 和結果。請等待任務進入 SUCCEEDED、FAILED 或 CANCELED 狀態後再刪除。

處於終止狀態（SUCCEEDED、FAILED 或 CANCELED）的任務會被刪除，且不會退還 credits。

回傳值

成功時返回 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 的形式回傳 Animation 任務物件的串流。

對於 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 日星期五 UTC 時間中午 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 物件參考請參見錯誤。
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 格式更改影格率後動畫的可下載 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

取得動畫列表

回傳動畫庫中的所有動畫，並依 action_id 排序。回應是一份完整列表而非分頁結果，因此一次呼叫即可填滿一個動作選擇器。過濾器可縮小結果範圍；若全部省略則回傳全部內容。

若想以肉眼瀏覽同一個目錄，並查看每個動作的動畫預覽，請參閱動畫庫參考。

此 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。

回傳

回傳一份由動畫物件組成的列表。

此處回傳的每個 action_id 都可被上文的建立動畫任務接受，且其接受的每個 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
該動作預覽動圖（GIF）的 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"
}