API Chuyển văn bản thành Chuyển động

Tạo các đoạn chuyển động nhân vật từ các mô tả ngôn ngữ tự nhiên. Miêu tả một hành động — "một nhân vật vẫy tay", "một zombie lảo đảo tiến về phía trước" — và nhận một đoạn chuyển động thô mà bạn có thể tái nhắm mục tiêu lên các nhân vật đã rig trong quy trình của bạn hoặc các công cụ DCC.

Kết quả đầu ra là một đoạn chuyển động độc lập: nó không yêu cầu và không gắn liền với mô hình nhân vật. Để rig một nhân vật trước, hãy xem API Rigging.

POST/openapi/v1/text-to-motion

Tạo một Tác vụ Chuyển văn bản thành Chuyển động

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

Một tác vụ với mode prime tốn 10 tín dụng và tạo ra 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 swift tốn 3 tín dụng và tạo nhanh hơn với mô hình chuyển động kinh tế 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
Chế độ 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 đầu ra FBX; swift nhanh hơn và rẻ hơn và xuất đầu ra BVH.
Name
duration
Type
number
Bắt buộc
Description
Thời lượng mục tiêu của đoạn phim chuyển động theo giây. Từ 2 đến 10, từng bước là 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 của tác vụ Chuyển văn bản thành Chuyển động mới tạo.

Các chế độ thất bại

Name
400 - Bad Request
Description
Yêu cầu không chấp nhận được. Nguyên nhân phổ biến:
- Prompt bị thiếu hoặc trống: prompt bị thiếu, trống, hoặc dài hơn 400 ký tự.
- Chế độ không hợp lệ: mode không phải prime hoặc swift.
- Thời lượng không hợp lệ: duration bị thiếu, 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
Tín dụng không đủ để thực hiện tác vụ này.
Name
403 - Forbidden
Description
Prompt đã bị gắn cờ bởi hệ thống phát hiện nội dung.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ.

Yêu cầu

POST

/openapi/v1/text-to-motion

# Tạo một đoạn phim chuyển động chỉ với tham số cần phải có
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
  }'

# Tạo một đoạn phim nhanh, kinh tế với chế độ Swift
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
  }'

Phản hồi

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

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

Lấy thông tin Nhiệm vụ Chuyển văn bản thành chuyển động

Endpoint này cho phép bạn lấy thông tin một nhiệm vụ Chuyển văn bản thành chuyển động khi có một id nhiệm vụ hợp lệ. Tham khảo Đối tượng Nhiệm vụ Chuyển văn bản thành chuyển động để xem những thuộc tính nào được bao gồm.

Các Tham số

Name
id
Type
path
Description
Định danh duy nhất cho nhiệm vụ Chuyển văn bản thành chuyển động cần lấy thông tin.

Trả về

Phản hồi chứa đối tượng Nhiệm vụ Chuyển văn bản thành chuyển động. Xem chi tiết tại mục Đối tượng Nhiệm vụ Chuyển văn bản thành chuyển động.

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 Nhiệm vụ Chuyển đổi Văn bản thành Chuyển động

Trả về một danh sách phân trang các nhiệm vụ Chuyển đổi Văn bản thành Chuyển động của người gọi, với nhiệm vụ mới nhất trước. Phân trang chuẩn thông qua page_num và page_size.

Phản hồi là một mảng các đối tượng Nhiệm vụ Chuyển đổi Văn bản thành Chuyển động.

Lưu ý rằng các nhiệm 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 Tài sản của Tôi trên ứng dụng web. Sử dụng endpoint này để tìm một nhiệm vụ mà bạn không còn ID của nó.

Yêu cầu

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

Phản hồi

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

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

Truyền phát một tác vụ Text to Motion

Endpoint này truyền phát cập nhật thời gian thực cho một tác vụ Text to Motion sử dụng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất cho tác vụ Text to Motion để truyền phát.

Trả về

Trả về một luồng của Các đối tượng Tác vụ Text to Motion dưới dạng Server-Sent Events.

Mỗi sự kiện message mang theo đối tượng tác vụ đầy đủ. Trong khi tác vụ đ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; 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

// Ví dụ sự kiện lỗi
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Các sự kiện Message mang theo đối tượng tác vụ đầy đủ ở mỗi giai đoạn; các trường kết quả
// vẫn trống cho đến khi tác vụ hoàn thành thành công.
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: { // Ví dụ về một mục tác vụ stream SUCCEEDED, phản chiếu cấu trúc của Đối tượng Tác vụ Text to Motion
  "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 nhiệm vụ Text to Motion

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

Tham số Đường dẫn

Name
id
Type
path
Description
ID của nhiệm vụ Text to Motion cần xóa.

Kết quả trả về

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

Yêu cầu

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

Phản hồi

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

Đối Tượng Nhiệm Vụ Chuyển Đổi Văn Bản Thành Chuyển Động

Đối tượng Nhiệm Vụ Chuyển Đổi Văn Bản Thành Chuyển Động đại diện cho đơn vị công việc để tạo ra một đoạn chuyển động từ một prompt văn bản.

Thuộc Tính

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

Đối Tượng Ví Dụ Nhiệm Vụ Chuyển Đổi Văn Bản Thành Chuyển Động

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