lowpoly sẽ ngừng hoạt động vào 30 thg 10, 2026. meshy-7 với vai trò mô hình tạo 3D sẽ ngừng hoạt động vào 31 thg 12, 2026; với vai trò mô hình texture thì vẫn dùng được. 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ợ

Text to Motion API

Tạo các đoạn clip chuyển động nhân vật từ mô tả văn bản. Mô tả một hành động, chẳng hạn như "một nhân vật đang vẫy tay" hoặc "một zombie lê bước về phía trước", và nhận về một đoạn clip chuyển động thô. Bạn có thể áp lại đoạn clip này lên các nhân vật đã được rig trong pipeline hoặc công cụ DCC của riêng bạn.

Đầu ra là một đoạn clip chuyển động độc lập. Nó không cần mô hình nhân vật, và cũng không được gắn với mô hình nào. Để rig một nhân vật trước, hãy xem Rigging API. Để áp dụng một đoạn clip lên nhân vật đã rig của bạn, hãy gửi id của tác vụ dưới dạng motion_task_id đến API Hoạt hình.

POST/openapi/v1/text-to-motion

Tạo tác vụ Text to Motion

Tạo một tác vụ Text to Motion, giúp tạo ra một đoạn chuyển động từ một prompt văn bản.

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

Một tác vụ prime tốn 10 tín dụng và sử dụng mô hình chuyển động chất lượng cao hơn của Meshy. Một tác vụ swift tốn 3 tín dụng và sử dụng mô hình chuyển động nhanh hơn, chi phí thấp hơn.

Request

POST
/openapi/v1/text-to-motion
# Generate a motion clip with required params only
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Generate a fast, economical clip with Swift mode
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

Tham số

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

    Văn bản mô tả chuyển động cần tạo, tối đa 400 ký tự. Văn bản dài hơn sẽ trả về 400.

  • Name
    mode
    Type
    string
    mặc định prime
    Description

    Mô hình chuyển động, đồng thời cũng xác định định dạng tệp của đoạn clip.

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

    • prime: chất lượng cao hơn, trả về một clip FBX
    • swift: nhanh hơn và rẻ hơn, trả về một clip BVH

    Bất kỳ giá trị nào khác sẽ trả về 400.

  • Name
    duration
    Type
    number
    Bắt buộc
    Description

    Độ dài mục tiêu của clip tính bằng giây, từ 2 đến 10 theo bước 0.5, ví dụ 2, 2.5, hoặc 3. Bất kỳ giá trị nào khác sẽ trả về 400.

Giá trị trả về

Trường result của phản hồi chứa ID của tác vụ Text to Motion mới.

Các chế độ lỗi

  • Name
    400 - Bad Request
    Description

    Yêu cầu không thể thực hiện. Thông báo lỗi sẽ cho biết vấn đề mà hệ thống phát hiện. Ví dụ:

    • Thiếu hoặc trống prompt: prompt bị thiếu, để trống, hoặc dài hơn 400 ký tự.
    • Mode không hợp lệ: mode không phải là prime hoặc swift.
    • Duration không hợp lệ: duration bị thiếu, nằm ngoài phạm vi 2 đến 10, hoặc không theo bước 0.5 giây.

    Hãy sửa yêu cầu rồi gửi lại. Xem Lỗi.

  • Name
    401 - Unauthorized
    Description

    Khóa API bị thiếu hoặc không hợp lệ. Hãy 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 giới hạn tín dụng. Hãy 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ụ cần có gói trả phí. Hãy nâng cấp gói của bạn trong cài đặt đăng ký, sau đó thử lại.
  • Name
    403 - Forbidden
    Description

    Hệ thống moderation nội dung đã gắn cờ cho prompt này. Hãy thay đổi prompt, sau đó gửi lại yêu cầu.

  • 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/text-to-motion/:id

Lấy một tác vụ Text to Motion

Trả về một tác vụ Text to Motion theo ID của nó.

Request

GET
/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791
curl https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Tham số

  • Name
    id
    Type
    path
    Description

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

Giá trị trả về

Đối tượng tác vụ Text to Motion.

GET/openapi/v1/text-to-motion

Liệt kê các tác vụ Text to Motion

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

Phản hồi là một mảng các đối tượng tác vụ Text to Motion.

Các tác vụ bạn tạo bằng API sẽ ở lại trong API và không xuất hiện trong My Assets trên ứng dụng web. Để 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/text-to-motion
curl "https://api.meshy.ai/openapi/v1/text-to-motion?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]
GET/openapi/v1/text-to-motion/:id/stream

Phát trực tiếp tác vụ Text to Motion

Phát trực tiếp các cập nhật của tác vụ Text to Motion dưới dạng Server-Sent Events (SSE).

Request

GET
/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream
curl -N https://api.meshy.ai/openapi/v1/text-to-motion/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 events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Text to Motion task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

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ụ Text to Motion dưới dạng Server-Sent Events.

Mỗi sự kiện message mang theo toàn bộ đối tượng tác vụ. Khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường result sẽ trống ("" hoặc 0), và finished_at cùng expires_at sẽ là 0. Để theo dõi tác vụ, hãy quan sát status và progress.

DELETE/openapi/v1/text-to-motion/:id

Xóa một tác vụ Text to Motion

Xóa vĩnh viễn một tác vụ Text to Motion, bao gồm cả đoạn clip chuyển động của nó. Bạn không thể hoàn tác việc xóa này.

Request

DELETE
/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -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ụ 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 tín dụng cho một tác vụ đã bắt đầu chạy, 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, rồi 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 thành công, hoặc 409 Conflict khi tác vụ đang ở trạng thái IN_PROGRESS.

Đối tượng task Text to Motion

Một đối tượng task Text to Motion mô tả quá trình tạo một clip chuyển động. Nó chứa trạng thái, progress, và clip khi task thành công.

Thuộc tính

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}
  • Name
    id
    Type
    string
    Description

    ID của task. Hãy coi đây là một chuỗi không minh bạch (opaque), và đừng phụ thuộc vào định dạng của nó.

  • Name
    type
    Type
    string
    Description

    Loại task, luôn là text-to-motion.

  • Name
    status
    Type
    string
    Description

    Trạng thái của task, 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 task, tính theo phần trăm từ 0 đến 100.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

    Thời điểm task hoàn tất, tính bằng mili giây Unix. Giá trị này là 0 cho đến khi task hoàn tất.

  • Name
    expires_at
    Type
    timestamp
    Description

    Thời điểm các tệp kết quả của task hết hạn, tính bằng mili giây Unix. Giá trị này là 0 cho đến khi task hoàn tất. Meshy giữ clip trong 3 ngày sau khi task hoàn tất, vì vậy hãy tải xuống trước thời hạn đó.

  • Name
    preceding_tasks
    Type
    integer
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Số lượng tín dụng mà task đã sử dụng, 10 cho mode prime hoặc 3 cho mode swift. Giá trị này là 0 đối với task FAILED, vì Meshy sẽ hoàn lại tín dụng khi task thất bại.

  • Name
    task_error
    Type
    object
    Description

    Thông tin chi tiết về lỗi khi task thất bại, và là null trong trường hợp khác. Xem Lỗi.

  • Name
    result
    Type
    object
    Description

    Clip chuyển động được tạo ra khi task thành công. Trước đó, các trường này vẫn tồn tại nhưng trống ("" hoặc 0).

    • Name
      motion_url
      Type
      string
      Description
      URL tải xuống cho clip chuyển động. Meshy ký lại URL này mỗi khi được đọc, và nó sẽ hết hạn theo khoảng thời gian lưu giữ của task.
    • Name
      motion_format
      Type
      string
      Description
      Định dạng tệp của clip, fbx cho mode prime hoặc bvh cho mode swift.
    • Name
      duration_ms
      Type
      integer
      Description
      Độ dài của clip, tính bằng mili giây.
    • Name
      mode
      Type
      string
      Description
      Mode mà Meshy sử dụng để tạo clip, prime hoặc swift.