Text to Motion API

Tạo các đoạn clip chuyển động của nhân vật từ mô tả bằng ngôn ngữ tự nhiên. Hãy mô tả một hành động — "một nhân vật đang vẫy tay", "một xác sống lê bước về phía trước" — và nhận về một đoạn clip chuyển động thô mà bạn có thể áp lại (retarget) lên các nhân vật đã được gắn khung xương (rigged) 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 yêu cầu, và cũng không được gắn liền với, một mô hình nhân vật. Để rigging một nhân vật trước, hãy xem Rigging API. Để áp một clip đã tạo lên nhân vật đã được rigging của bạn, hãy truyền id của task dưới dạng motion_task_id cho Animation API — hãy áp dụng nó trong khoảng thời gian lưu giữ tài nguyên 3 ngày.

POST/openapi/v1/text-to-motion

Tạo tác vụ Text to Motion

Endpoint này tạo một tác vụ mới để tạo một đoạn chuyển động (motion clip) từ một prompt văn bản.

Một tác vụ với mode là prime tốn 10 tín dụng và tạo bằng mô hình chuyển động chất lượng cao nhất của chúng tôi. Một tác vụ với mode là swift tốn 3 tín dụng và tạo nhanh hơn với mô hình chuyển động tiết kiệm của chúng tôi.

Tham số

Name
prompt
Type
string
Bắt buộc
Description
Mô tả bằng ngôn ngữ tự nhiên về chuyển động cần tạo. Tối đa 400 ký tự.
Name
mode
Type
string
mặc định prime
Description
Mode tạo chuyển động. Các giá trị khả dụng: prime, swift. prime tạo ra chất lượng cao nhất và xuất ra FBX; swift nhanh hơn và rẻ hơn, xuất ra BVH.
Name
duration
Type
number
Bắt buộc
Description
Thời lượng mục tiêu của đoạn chuyển động tính bằng giây. Từ 2 đến 10, theo bước 0.5 (ví dụ 2, 2.5, 3, … 10).

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ụ Text to Motion vừa được tạo.

Các chế độ thất bạ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 hoặc rỗ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 khoảng 2–10, hoặc không theo bước 0.5 giây.
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
403 - Forbidden
Description
Prompt đã bị đánh dấu bởi hệ thống moderation nội dung.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

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

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

Truy xuất một Text to Motion Task

Endpoint này cho phép bạn truy xuất một Text to Motion task với một id task hợp lệ. Tham khảo The Text to Motion 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 Text to Motion task cần truy xuất.

Giá trị trả về

Phản hồi chứa Text to Motion Task object. Xem chi tiết tại phần The Text to Motion Task Object.

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
}

GET/openapi/v1/text-to-motion

Danh sách tác vụ Text to Motion

Trả về danh sách được phân trang các tác vụ Text to Motion 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.

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

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 mục 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/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

Truyền trực tiếp một Task Text to Motion

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

Tham số

Name
id
Type
path
Description
Mã định danh duy nhất của task Text to Motion cần truyền trực tiếp.

Giá trị trả về

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

Mỗi sự kiện message mang theo toàn bộ đối tượng task. Trong khi task đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường result vẫn còn trống ("" / 0) và finished_at / expires_at là 0; hãy theo dõi status và progress.

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 stream item, mirroring The Text to Motion Task Object structure
  "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
}

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

Xóa một Task Text to Motion

Endpoint này xóa vĩnh viễn một task Text to Motion, bao gồm cả đoạn clip chuyển động đã được tạo. Hành động này không thể hoàn tác.

Path Parameters

Name
id
Type
path
Description
ID của task Text to Motion cần xóa.

Kết quả trả về

Trả về 200 OK khi thành công.

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

// Returns 200 Ok on success.

Đối tượng Task Text to Motion

Đối tượng Task Text to Motion đại diện cho đơn vị công việc để tạo một đoạn motion từ một prompt văn bản.

Thuộc tính

Name
id
Type
string
Description
Định danh duy nhất cho task.
Name
type
Type
string
Description
Loại của task. Giá trị là text-to-motion.
Name
status
Type
string
Description
Trạng thái của task. Các giá trị có thể: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress của task (0-100).
Name
created_at
Type
timestamp
Description
Dấu thời gian (milliseconds tính từ epoch) khi task được tạo.
Một dấu thời gian đại diện cho số milliseconds đã trôi qua từ ngày 1 tháng 1 năm 1970 UTC, theo chuẩn RFC 3339. Ví dụ, thứ Sáu, ngày 1 tháng 9 năm 2023 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 (milliseconds tính từ epoch) khi task bắt đầu xử lý. 0 nếu chưa bắt đầu.
Name
finished_at
Type
timestamp
Description
Dấu thời gian (milliseconds tính từ epoch) khi task hoàn thành. 0 nếu chưa hoàn thành.
Name
expires_at
Type
timestamp
Description
Dấu thời gian (milliseconds tính từ epoch) khi các asset kết quả của task hết hạn. 0 cho đến khi task hoàn thành. Đoạn clip được tạo ra sẽ được lưu giữ trong 3 ngày sau khi task hoàn thành; hãy tải xuống trước khi nó hết hạn.
Name
preceding_tasks
Type
integer
Description
Số lượng task đang chờ xử lý trước trong hàng đợi. Chỉ có ý nghĩa khi status là PENDING; bị bỏ qua khi giá trị bằng không.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã bị tiêu thụ bởi task này. 10 cho mode prime, 3 cho mode swift. Trả về 0 đối với các task FAILED (tín dụng được hoàn lại khi thất bại).
Name
task_error
Type
object
Description
Chi tiết lỗi cho các task thất bại; null trừ khi task FAILED. Xem Lỗi để tham khảo đầy đủ về đối tượng task_error.
Name
result
Type
object
Description
Chứa đoạn motion clip được tạo ra khi task SUCCEEDED; trước đó các trường vẫn tồn tại nhưng trống ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL để tải xuống đoạn motion clip được tạo ra. URL này được ký lại mỗi lần đọc và hết hạn theo khung thời gian lưu giữ của task.
- Name
  motion_format
  Type
  string
  Description
  Định dạng file của clip: fbx cho mode prime, bvh cho mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Thời lượng của clip được tạo ra, tính bằng milliseconds.
- Name
  mode
  Type
  string
  Description
  Mode mà clip được tạo ra với: prime hoặc swift.

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
}