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.

Rigging API

Rigging API cho phép bạn thêm khung xương (bộ xương) vào các mô hình 3D hình người một cách tự động thông qua lập trình, liên kết lưới với khung xương đó để sẵn sàng cho việc tạo hoạt hình. Để áp dụng Hoạt hình cho nhân vật đã được rigging, xem Animation API.

Xin lưu ý rằng tại thời điểm hiện tại, rigging bằng lập trình hiện chỉ hoạt động tốt với các asset hình người tiêu chuẩn (dạng hai chân) có tay chân và cấu trúc cơ thể được xác định rõ ràng.

POST/openapi/v1/rigging

Create a Rigging Task

Endpoint này cho phép bạn tạo một tác vụ rigging mới cho một mô hình 3D nhất định. Khi hoàn thành thành công, nó cung cấp một nhân vật đã được rig ở các định dạng tiêu chuẩn và tùy chọn kèm theo các hoạt ảnh đi bộ/chạy cơ bản.

Tác vụ chạy ngầm. Để biết thời gian xử lý thường mất bao lâu, xem Thời gian xử lý.

Hiện tại, tính năng tự động rigging không phù hợp với các mô hình sau:

  • Lưới chưa có texture
  • Asset không phải hình người
  • Asset hình người có cấu trúc chi và cơ thể không rõ ràng

Khi sử dụng input_task_id, các mô hình có hơn 300.000 mặt (faces) không được hỗ trợ để rig. Vui lòng sử dụng Remesh API để giảm số lượng mặt trước khi rig.

Khi sử dụng model_url, mặt của nhân vật phải hướng về trục +Z (hướng tiến chuẩn của glTF). Các mô hình hướng theo trục khác sẽ thất bại trong việc ước tính tư thế.

Tham số

Chỉ bắt buộc một trong hai trường input_task_id hoặc model_url. Nếu cả hai đều được cung cấp, input_task_id sẽ được ưu tiên.

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

    Tác vụ đầu vào cần được rig. Hiện tại chúng tôi hỗ trợ các mô hình hình người có texture.

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

    Vui lòng cung cấp một mô hình 3D để Meshy rig thông qua một URL có thể truy cập công khai hoặc Data URI. Hiện tại chúng tôi hỗ trợ các file GLB hình người có texture (định dạng .glb).

    Kích thước file tối đa: 400 MB đối với URL http hoặc https, 100 MB đối với data: URI.

    Một file vượt quá 100 MB với hơn 10.000.000 mặt sẽ trả về 400. Các mặt được tính là tam giác, và một lưới được vẽ nhiều lần sẽ được tính một lần cho mỗi bản sao. Một file GLB vượt quá 100 MB không được sử dụng nén Draco.

  • Name
    height_meters
    Type
    number
    mặc định 1.7
    Description

    Chiều cao gần đúng của mô hình nhân vật tính bằng mét. Điều này hỗ trợ cho độ chính xác về tỷ lệ và rigging. Giá trị này phải là một số dương.

  • Name
    texture_image_url
    Type
    string
    Description

    Hình ảnh texture màu cơ bản đã được trải UV (UV-unwrapped) của mô hình. URL có thể truy cập công khai hoặc Data URI. Hiện tại chúng tôi hỗ trợ định dạng .png.

    Kích thước file tối đa: 20 MB.

Kết quả trả về

Thuộc tính result của phản hồi chứa id tác vụ của tác vụ rigging vừa được tạo.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:

    • Thiếu tham số: Phải cung cấp model_url hoặc input_task_id.
    • Định dạng mô hình không hợp lệ: model_url trỏ đến một file có phần mở rộng không được hỗ trợ (chỉ hỗ trợ .glb).
    • URL không thể truy cập: Không thể tải xuống file từ model_url.
    • File mô hình quá lớn: File model_url vượt quá 400 MB (URL http hoặc https) hoặc 100 MB (data: URI).
    • Quá nhiều mặt: File model_url vượt quá 100 MB và có hơn 10.000.000 mặt. Hãy giảm số lượng mặt, sau đó gửi lại file.
    • File mô hình không thể đọc được: File model_url vượt quá 100 MB và không thể đọc được header của nó, ví dụ như một file GLB được nén Draco.
    • Header mô hình quá phức tạp: File model_url vượt quá 100 MB và header của nó có quá nhiều lưới, node hoặc bản ghi cần kiểm tra. Hãy giảm số lượng đối tượng trong file, sau đó gửi lại.
    • Hình ảnh quá lớn: Hình ảnh texture_image_url vượt quá 20 MB.
    • Tác vụ đầu vào không hợp lệ: input_task_id không trỏ đến một tác vụ API hợp lệ.
    • Vượt quá số lượng mặt: Mô hình đầu vào có hơn 300.000 mặt. Vui lòng sử dụng Remesh API để giảm số lượng mặt trước khi rig.
  • Name
    401 - Unauthorized
    Description

    Xác thực thất bại. Vui lòng kiểm tra khóa API của bạn.

  • Name
    402 - Payment Required
    Description

    Không đủ tín dụng để thực hiện tác vụ này.

  • Name
    422 - Unprocessable Entity
    Description

    Ước tính tư thế thất bại. Mô hình được cung cấp có thể không phải là một nhân vật hình người hợp lệ.

  • Name
    429 - Too Many Requests
    Description

    Bạn đã vượt quá giới hạn tốc độ.

Request

POST
/openapi/v1/rigging
# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}
GET/openapi/v1/rigging/:id

Retrieve a Rigging Task

endpoint này cho phép bạn truy xuất một tác vụ rigging dựa trên id tác vụ hợp lệ. Tham khảo The Rigging Task Object để xem các thuộc tính được bao gồm.

Tham số

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất của tác vụ rigging cần truy xuất.

Kết quả trả về

Phản hồi chứa đối tượng Rigging Task. Xem phần The Rigging Task Object để biết chi tiết.

Request

GET
/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579
curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}
DELETE/openapi/v1/rigging/:id

Xóa một Tác vụ Rigging

Endpoint này xóa vĩnh viễn một tác vụ rigging, bao gồm tất cả các mô hình và dữ liệu liên quan. Hành động này không thể hoàn tác.

Tham số Đường dẫn

  • Name
    id
    Type
    path
    Description

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

Trạng thái Tác vụ

Một tác vụ vẫn còn ở trạng thái PENDING sẽ được xóa và số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại.

Một tác vụ đã ở trạng thái IN_PROGRESS thì không thể xóa: yêu cầu sẽ bị từ chối với 409 Conflict và tác vụ vẫn tiếp tục chạy. Tín dụng cho một tác vụ mà worker đã bắt đầu xử lý sẽ không được hoàn lại, vì vậy việc xóa nó giữa chừng 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.

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

Giá trị Trả về

Trả về 200 OK khi thành công, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

Request

DELETE
/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/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/rigging

List Rigging Tasks

Trả về danh sách có phân trang các tác vụ rigging của người gọi, mới nhất trước. Phân trang tiêu chuẩn thông qua page_num và page_size.

Lưu ý rằng các tác vụ được tạo thông qua API được quản lý thông qua API — chúng không xuất hiện trong My Assets của ứng dụng web. Sử dụng endpoint này để tìm một tác vụ mà bạn không còn ID.

Request

GET
/openapi/v1/rigging
curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/rigging/:id/stream

Stream a Rigging Task

Endpoint này truyền trực tiếp các cập nhật theo thời gian thực cho một tác vụ Rigging bằng Server-Sent Events (SSE).

Tham số

  • Name
    id
    Type
    path
    Description

    Định danh duy nhất của tác vụ Rigging cần truyền trực tiếp.

Giá trị trả về

Trả về một luồng The Rigging Task Objects dưới dạng Server-Sent Events.

Đối với các tác vụ PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ chỉ bao gồm các trường cần thiết là progress và status.

Request

GET
/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream
curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

The Rigging Task Object

Đối tượng Rigging Task đại diện cho đơn vị công việc để rigging một nhân vật.

Thuộc tính

  • Name
    id
    Type
    string
    Description

    Định danh duy nhất cho tác vụ.

  • Name
    type
    Type
    string
    Description

    Loại của tác vụ Rigging. Giá trị là rig.

  • Name
    status
    Type
    string
    Description

    Trạng thái của tác vụ. Các giá trị có thể: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Tiến trình của tác vụ (0-100). 0 nếu chưa bắt đầu, 100 nếu thành công.

  • Name
    created_at
    Type
    timestamp
    Description

    Dấu thời gian (mili giây kể từ epoch) khi tác vụ được tạo.

    Một dấu thời gian đại diện cho số mili giây đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, theo tiêu chuẩn RFC 3339. Ví dụ, Thứ Sáu, ngày 1 tháng 9 năm 2023 lúc 12:00:00 PM GMT được biểu diễn là 1693569600000. Điều này áp dụng cho tất cả các dấu thời gian trong Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Dấu thời gian (mili giây kể từ epoch) khi tác vụ bắt đầu xử lý. 0 nếu chưa bắt đầu.

  • Name
    finished_at
    Type
    timestamp
    Description

    Dấu thời gian (mili giây kể từ epoch) khi tác vụ hoàn thành. 0 nếu chưa hoàn thành.

  • Name
    expires_at
    Type
    timestamp
    Description

    Dấu thời gian (mili giây kể từ epoch) khi các asset kết quả của tác vụ hết hạn và có thể bị xóa.

  • Name
    task_error
    Type
    object
    Description

    Chi tiết lỗi cho các tác vụ thất bại. Xem Lỗi để biết tham chiếu đầy đủ về đối tượng task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Số lượng tín dụng đã tiêu thụ bởi tác vụ này. Có mặt khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).

  • Name
    result
    Type
    object
    Description

    Chứa các URL asset đầu ra nếu tác vụ SUCCEEDED, null nếu không.

    • Name
      rigged_character_fbx_url
      Type
      string
      Description

      URL để tải xuống nhân vật đã rig ở định dạng FBX.

    • Name
      rigged_character_glb_url
      Type
      string
      Description

      URL để tải xuống nhân vật đã rig ở định dạng GLB.

    • Name
      basic_animations
      Type
      object (optional)
      Description

      Chứa các URL cho hoạt hình mặc định. (ví dụ: nếu generate_basic_animations ngầm định là true hoặc được bật theo mặc định).

      • Name
        walking_glb_url
        Type
        string
        Description
        URL để tải xuống hoạt hình đi bộ ở định dạng GLB (có da).
      • Name
        walking_fbx_url
        Type
        string
        Description
        URL để tải xuống hoạt hình đi bộ ở định dạng FBX (có da).
      • Name
        walking_armature_glb_url
        Type
        string
        Description
        URL để tải xuống bộ xương hoạt hình đi bộ ở định dạng GLB.
      • Name
        running_glb_url
        Type
        string
        Description
        URL để tải xuống hoạt hình chạy ở định dạng GLB (có da).
      • Name
        running_fbx_url
        Type
        string
        Description
        URL để tải xuống hoạt hình chạy ở định dạng FBX (có da).
      • Name
        running_armature_glb_url
        Type
        string
        Description
        URL để tải xuống bộ xương hoạt hình chạy ở định dạng GLB.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Số lượng tác vụ đứng trước trong hàng đợi. Chỉ có ý nghĩa nếu trạng thái là PENDING.

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}