lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. Hãy chuyển sang mô hình khác trước các ngày này để tránh lỗi yêu cầu. Xem tất cả mục ngừng hỗ trợ

API Hoạt hình

Áp dụng hoạt hình cho các nhân vật đã có rig, và liệt kê các hoạt hình mà bạn có thể áp dụng.

POST/openapi/v1/animations

Tạo một tác vụ Hoạt hình

Tạo một tác vụ Hoạt hình, áp dụng một hoạt hình cho nhân vật mà bạn đã rig trước đó. Hoạt hình có thể là một trong các loại sau:

  • Một hành động có sẵn từ thư viện hoạt hình (action_id)
  • Nhiều hành động có sẵn được gộp vào một tệp (action_ids)
  • Một đoạn chuyển động bạn tạo bằng Text to Motion API (motion_task_id)

Bạn cũng có thể xử lý hậu kỳ đầu ra. Tác vụ chạy trong nền. Để biết một tác vụ thường mất bao lâu, xem Thời gian xử lý.

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

Tham số

  • Name
    rig_task_id
    Type
    string
    Bắt buộc
    Description

    ID của tác vụ Rigging có nhân vật cần tạo hoạt hình, từ POST /openapi/v1/rigging. Tác vụ đó phải có trạng thái SUCCEEDED.

Gửi đúng một trong ba tham số action_id, action_ids, và motion_task_id.

  • Name
    action_ids
    Type
    array of integers
    Bắt buộc
    Description

    Bắt buộc trừ khi bạn gửi action_id hoặc motion_task_id. ID của 1 đến 10 hoạt hình có sẵn cần áp dụng cùng lúc, không được trùng lặp. Nếu gửi quá 10 ID, hoặc một ID bị lặp lại, sẽ trả về lỗi 400. Để xem các ID, xem tài liệu tham khảo Thư viện hoạt hình.

    Meshy trả về một tệp với một đoạn hoạt hình cho mỗi hành động, phù hợp với state machine trong game engine. Meshy tính phí cho mỗi hành động trong danh sách. Xem Giá.

    Một danh sách chỉ có một ID hoạt động giống như gửi ID đó dưới dạng action_id.

  • Name
    motion_task_id
    Type
    string
    Bắt buộc
    Description

    Bắt buộc trừ khi bạn gửi action_id hoặc action_ids. ID của một tác vụ Text to Motion có đoạn hoạt hình cần áp dụng thay cho một hành động có sẵn. Tác vụ đó phải có trạng thái SUCCEEDED, và rig phải là dạng hai chân (biped).

    Meshy sẽ retarget đoạn hoạt hình đó lên nhân vật đã được rig. Meshy sao chép đoạn hoạt hình khi bạn tạo tác vụ này, nên tác vụ này sẽ không bị ảnh hưởng nếu tác vụ Text to Motion sau đó hết hạn hoặc bạn xóa nó. Meshy giữ các tệp của tác vụ Text to Motion trong 3 ngày, vì vậy hãy áp dụng đoạn hoạt hình trước thời điểm đó.

  • Name
    post_process
    Type
    object
    Description

    Xử lý hậu kỳ cho đầu ra hoạt hình. Bỏ qua tham số này để nhận các tệp hoạt hình tiêu chuẩn.

    Với motion_task_id, quá trình retarget có thể chỉ tạo ra hoạt hình dạng GLB. Nếu bạn gửi post_process mà không có tệp FBX nào khả dụng, tác vụ sẽ thất bại với task_error, và Meshy sẽ hoàn lại tín dụng cho bạn. Nếu không gửi post_process, tác vụ sẽ thành công, và animation_fbx_url sẽ trống.

Chỉ áp dụng khi post_process is set
  • Name
    operation_type
    Type
    string
    Description

    Thao tác cần chạy. Nếu không có tham số này, Meshy sẽ không tạo thêm tệp nào. Một giá trị không nằm trong danh sách sau sẽ trả về lỗi 400.

    Các giá trị khả dụng:

    • change_fps: thay đổi tốc độ khung hình thành fps
    • fbx2usdz: chuyển đổi hoạt hình sang USDZ
    • extract_armature: trích xuất bộ xương dưới dạng tệp FBX
  • Name
    fps
    Type
    integer
    mặc định 30
    Description

    Tốc độ khung hình cần đổi thành, một trong các giá trị 24, 25, 30, hoặc 60. Chỉ áp dụng khi operation_type là change_fps. Mọi giá trị khác sẽ trả về lỗi 400.

Với action_ids, tác vụ trả về một tệp gộp duy nhất thay vì một tệp cho mỗi hành động. animation_glb_url và animation_fbx_url mỗi cái đều trỏ đến một tệp chứa mọi hành động được yêu cầu dưới dạng một đoạn clip riêng biệt. Trong tệp đó:

  • Thứ tự clip: theo thứ tự của mảng action_ids, không phải thứ tự số của các ID.
  • Tên clip: tên của hoạt hình trong thư viện. Các tên này khớp với tên bạn nhận được khi xuất tất cả hoạt hình của một nhân vật thành một tệp từ ứng dụng web Meshy. Nếu hai ID được yêu cầu có cùng tên clip, Meshy sẽ thêm action_id vào tên clip xuất hiện sau để giữ các tên là duy nhất.
  • Xử lý hậu kỳ: Meshy áp dụng việc này cho tệp đã gộp, không áp dụng cho từng clip riêng lẻ.

Giá trị trả về

Trường result của phản hồi chứa ID của tác vụ Hoạt hình mới.

Các trường hợp thất bại

  • Name
    400 - Bad Request
    Description

    Không thể chạy yêu cầu này. Thông báo lỗi sẽ cho biết vấn đề đã phát hiện. Ví dụ:

    • Thiếu tham số: rig_task_id bị thiếu, hoặc không có tham số nào trong số action_id, action_ids, và motion_task_id được gửi.
    • Tham số xung đột: Yêu cầu có nhiều hơn một trong các tham số action_id, action_ids, và motion_task_id. Chỉ gửi một tham số.
    • Tác vụ rig không hợp lệ: rig_task_id không phải là một ID tác vụ hợp lệ, không phải là một tác vụ Rigging, hoặc trỏ đến một tác vụ chưa thành công.
    • ID hành động không hợp lệ: action_id, hoặc một mục trong action_ids, không phải là một hoạt hình hợp lệ.
    • Quá nhiều hành động: action_ids có nhiều hơn 10 ID.
    • Hành động trùng lặp: action_ids có cùng một ID xuất hiện nhiều hơn một lần.
    • Tác vụ chuyển động chưa sẵn sàng: Tác vụ motion_task_id chưa đạt trạng thái SUCCEEDED.
    • Rig không được hỗ trợ: motion_task_id cần một rig hai chân (biped), và Meshy từ chối rig bốn chân (quadruped).

    Sửa lại yêu cầu, sau đó gửi lại. Xem Lỗi.

  • Name
    401 - Unauthorized
    Description

    Khóa API bị thiếu hoặc không hợp lệ. Kiểm tra header Authorization.

  • Name
    402 - Payment Required
    Description

    Ví dụ:

    • Không đủ tín dụng: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt đến giới hạn tín dụng. Kiểm tra số dư tín dụng của bạn, sau đó thử lại.
    • Gói miễn phí: Tạo tác vụ yêu cầu một gói trả phí. Nâng cấp gói của bạn trong cài đặt đăng ký, sau đó thử lại.
  • Name
    403 - Forbidden
    Description

    Tác vụ rig_task_id là một mô hình phù điêu (bas-relief), mà endpoint này không thể tạo hoạt hình. Thông báo là This model type does not support this operation. Hãy rig một mô hình khác.

  • Name
    404 - Not Found
    Description

    Meshy không thể tìm thấy tác vụ hoặc tệp mà yêu cầu cần. Một trong các trường hợp sau đã xảy ra:

    • Meshy không thể tìm thấy tác vụ rig_task_id trong số các tác vụ của bạn. Kiểm tra lại ID.
    • Meshy đã xóa các tệp của tác vụ rig_task_id sau expires_at của nó. Hãy rig lại nhân vật.
    • Meshy không thể tìm thấy tác vụ motion_task_id. Kiểm tra lại ID.
    • Đoạn chuyển động đã hết hạn, vì Meshy chỉ giữ các tệp của một tác vụ Text to Motion trong 3 ngày. Hãy tạo một tác vụ Text to Motion khác.
  • Name
    429 - Too Many Requests
    Description

    Bạn đã vượt quá giới hạn tốc độ. Hãy chờ, sau đó thử lại. Xem Giới hạn tốc độ.

GET/openapi/v1/animations/:id

Lấy tác vụ Hoạt hình

Trả về một tác vụ Hoạt hình theo ID của nó.

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": null,
  "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=..."
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

    ID tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

Đối tượng tác vụ Hoạt hình.

DELETE/openapi/v1/animations/:id

Xóa một tác vụ Hoạt hình

Xóa vĩnh viễn một tác vụ Hoạt hình, bao gồm cả các mô hình và dữ liệu của nó. Bạn không thể hoàn tác việc xóa.

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

Tham số đường dẫn

  • Name
    id
    Type
    path
    Description

    ID của tác vụ cần xóa.

Trạng thái tác vụ

Xóa một tác vụ ở trạng thái PENDING sẽ hoàn lại số tín dụng đã sử dụng khi bạn tạo tác vụ đó.

Một tác vụ IN_PROGRESS không thể bị xóa. Yêu cầu sẽ trả về 409 Conflict, và tác vụ vẫn tiếp tục chạy. Meshy không hoàn lại tín dụng cho một tác vụ đã bắt đầu, vì vậy việc xóa nó sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho đến khi tác vụ đạt trạng thái SUCCEEDED, FAILED, hoặc CANCELED, sau đó mới xóa.

Xóa một tác vụ ở trạng thái cuối cùng (SUCCEEDED, FAILED, hoặc CANCELED) sẽ không hoàn lại tín dụng.

Giá trị trả về

200 OK khi tác vụ được xóa, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

GET/openapi/v1/animations

List Animation tasks

Trả về danh sách phân trang các tác vụ Hoạt hình của bạn, mới nhất trước. Để duyệt qua danh sách, sử dụng page_num và page_size.

Các tác vụ bạn tạo thông qua API sẽ không xuất hiện trong My Assets trên ứng dụng web, vì vậy bạn quản lý chúng thông qua API. Để tìm một tác vụ mà bạn không còn ID, hãy sử dụng endpoint này.

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

Truyền trực tiếp một tác vụ Hoạt hình

Truyền trực tiếp các cập nhật của tác vụ Hoạt hình dưới dạng Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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, with the same structure as the 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": null,
  "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?..."
  }
}

Tham số

  • Name
    id
    Type
    path
    Description

    ID tác vụ từ phản hồi tạo.

Giá trị trả về

Một luồng đối tượng tác vụ Hoạt hình dưới dạng Server-Sent Events.

Mỗi sự kiện chứa toàn bộ đối tượng tác vụ, theo cùng cấu trúc mà endpoint Get trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường kết quả của nó chưa có giá trị.

Đối tượng tác vụ Animation (Hoạt hình)

Một đối tượng tác vụ Animation mô tả một hoạt hình được áp dụng cho một nhân vật đã được gắn bộ xương. Nó chứa trạng thái, progress, và các tệp hoạt hình khi tác vụ thành công.

Thuộc tính

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": null,
  "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?..."
  }
}
  • Name
    id
    Type
    string
    Description

    ID của tác vụ. Hãy xem đây là một chuỗi không minh bạch, và đừng dựa vào định dạng của nó.

  • Name
    type
    Type
    string
    Description

    Loại tác vụ, luôn là animate.

  • Name
    status
    Type
    string
    Description

    Trạng thái của tác vụ, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, hoặc CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Mức độ hoàn thành của tác vụ, tính theo phần trăm. Giá trị là 0 cho đến khi tác vụ bắt đầu và 100 khi tác vụ thành công.

  • Name
    created_at
    Type
    timestamp
    Description

    Thời điểm tác vụ được tạo, tính bằng mili giây Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Thời điểm tác vụ bắt đầu, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ bắt đầu.

  • Name
    finished_at
    Type
    timestamp
    Description

    Thời điểm tác vụ kết thúc, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ kết thúc.

  • Name
    expires_at
    Type
    timestamp
    Description

    Thời điểm các tệp kết quả của tác vụ hết hạn, tính bằng mili giây Unix.

  • Name
    task_error
    Type
    object
    Description

    Thông tin chi tiết về lỗi khi tác vụ thất bại. Giá trị là null trừ khi trạng thái là FAILED. Xem Lỗi.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số tín dụng mà tác vụ đã sử dụng. Có mặt khi trạng thái là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Giá trị là 0 đối với tác vụ FAILED, vì Meshy sẽ hoàn lại tín dụng khi một tác vụ thất bại.

  • Name
    result
    Type
    object
    Description

    URL tải xuống cho các tệp hoạt hình, khi tác vụ có trạng thái SUCCEEDED.

    • Name
      animation_glb_url
      Type
      string
      Description
      Hoạt hình dưới dạng tệp GLB. Đối với tác vụ được tạo bằng action_ids, tệp duy nhất này chứa mọi hành động được yêu cầu dưới dạng các clip riêng biệt.
    • Name
      animation_fbx_url
      Type
      string
      Description
      Hoạt hình dưới dạng tệp FBX. Đối với tác vụ được tạo bằng action_ids, tệp duy nhất này chứa mọi hành động được yêu cầu dưới dạng các clip riêng biệt.
    • Name
      processed_usdz_url
      Type
      string
      Description
      Hoạt hình đã qua xử lý dưới dạng tệp USDZ.
    • Name
      processed_armature_fbx_url
      Type
      string
      Description
      Bộ xương đã qua xử lý dưới dạng tệp FBX.
    • Name
      processed_animation_fps_fbx_url
      Type
      string
      Description
      Hoạt hình với tốc độ khung hình đã thay đổi, dưới dạng tệp FBX, ví dụ như khi bạn đã sử dụng thao tác change_fps.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Giá trị này chỉ có ý nghĩa khi tác vụ đang ở trạng thái PENDING. Trường này sẽ không xuất hiện khi giá trị là 0.

GET/openapi/v1/animations/library

Liệt kê hoạt hình

Trả về mọi hoạt hình trong thư viện, được sắp xếp theo action_id. Phản hồi là danh sách đầy đủ, không phân trang, nên chỉ một lệnh gọi cũng đủ để điền vào bộ chọn hành động. Các bộ lọc giúp thu hẹp kết quả. Để lấy toàn bộ hoạt hình, hãy bỏ qua tất cả các bộ lọc.

Để duyệt cùng danh sách này với bản xem trước dạng hoạt hình cho mỗi hành động, xem tài liệu tham khảo Thư viện hoạt hình.

Yêu cầu này không tốn tín dụng.

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

Tham số

  • Name
    search
    Type
    string
    Description

    Văn bản cần tìm kiếm. Meshy trả về các hoạt hình có name hoặc key chứa văn bản này, không phân biệt chữ hoa chữ thường. Meshy khớp văn bản theo nghĩa đen, nên % và _ không phải là ký tự đại diện.

  • Name
    category
    Type
    string
    Description

    Danh mục cần liệt kê, khớp chính xác. Một danh mục không xác định sẽ trả về danh sách rỗng.

    Các giá trị khả dụng:

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

    Danh mục con cần liệt kê, khớp chính xác. Bạn có thể gửi nó mà không cần category. Tên danh mục con không duy nhất giữa các danh mục. Ví dụ, Transitioning thuộc cả Fighting và DailyActions. Vì vậy nếu không có category, bộ lọc sẽ khớp danh mục con trong mọi danh mục.

  • Name
    action_ids
    Type
    string
    Description

    Các hoạt hình cần trả về, dưới dạng tối đa 200 giá trị action_id cách nhau bằng dấu phẩy. Dùng tham số này để tra cứu các ID cụ thể thay vì duyệt danh sách. Nhiều hơn 200 ID sẽ trả về 400.

    Phản hồi sẽ bỏ qua một ID mà không hoạt hình nào có. Vì vậy bạn cũng có thể dùng bộ lọc này để kiểm tra xem các ID bạn đã lưu trữ còn khả dụng hay không.

Kết hợp các bộ lọc

Meshy áp dụng các bộ lọc cùng lúc. Mỗi bộ lọc thu hẹp kết quả, nên Meshy chỉ trả về một hoạt hình nếu nó khớp với tất cả các bộ lọc. Trong cùng một bộ lọc, bất kỳ giá trị nào của nó cũng có thể khớp. Ví dụ, search khớp với name hoặc key, và action_ids khớp với bất kỳ ID nào trong danh sách.

Vì vậy, một tổ hợp không có điểm chung sẽ trả về mảng rỗng, không phải lỗi. Hành động 92 là "Double Combo Attack", một hoạt hình Fighting. Ví dụ:

  • ?action_ids=92&category=Fighting trả về hành động 92.
  • ?action_ids=92&category=Dancing trả về [], vì nó không phải là hoạt hình Dancing.
  • ?action_ids=92&search=walk trả về [], vì tên của nó không khớp với walk.

Để lấy các hoạt hình cụ thể trong bất kỳ danh mục nào, chỉ cần gửi riêng action_ids.

Giá trị trả về

Một danh sách các đối tượng hoạt hình.

Tạo một tác vụ Hoạt hình chấp nhận mọi action_id mà endpoint này trả về, và endpoint này trả về mọi ID mà việc tạo chấp nhận. Cả hai đều không bao gồm các hoạt hình đã ngừng sử dụng. Nếu bạn lưu bộ nhớ đệm cho thư viện, hãy làm mới nó theo thời gian, để một ID đã ngừng sử dụng không còn tồn tại trong bộ chọn của bạn.

The animation object

Một đối tượng hoạt hình mô tả một hoạt hình trong thư viện.

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"
}
  • Name
    action_id
    Type
    integer
    Description

    Giá trị cần gửi dưới dạng action_id khi bạn tạo một tác vụ Hoạt hình. Giá trị này là duy nhất và ổn định, nhưng không liên tục. Các hoạt hình đã ngừng sử dụng để lại khoảng trống trong việc đánh số, vì vậy đừng cho rằng mọi ID trong một phạm vi đều hợp lệ.

  • Name
    name
    Type
    string
    Description

    Tên hiển thị của hoạt hình. Tên này không phải là duy nhất, vì một số hoạt hình dùng chung tên với một biến thể khác. Để xác định một hoạt hình, hãy dùng action_id hoặc key.

  • Name
    key
    Type
    string
    Description

    Một slug duy nhất, ổn định cho hoạt hình. Hãy dùng nó khi bạn cần một ID không phải dạng số để làm khóa cho kho lưu trữ của riêng bạn.

  • Name
    category
    Type
    string
    Description

    Nhóm cấp cao nhất, ví dụ Fighting.

  • Name
    sub_category
    Type
    string
    Description

    Nhóm trong danh mục, ví dụ AttackingwithWeapon.

  • Name
    preview_url
    Type
    string
    Description

    URL của ảnh GIF động xem trước của hành động. Bạn có thể hiển thị trực tiếp nó trong bộ chọn của riêng mình.