Text to Motion API

สร้างคลิปการเคลื่อนไหวของตัวละครจากคำอธิบายข้อความ อธิบายการกระทำ เช่น "ตัวละครกำลังโบกมือ" หรือ "ซอมบี้เดินโซเซไปข้างหน้า" แล้วรับคลิปการเคลื่อนไหวดิบ คุณสามารถรีทาร์เก็ตคลิปไปยังตัวละครที่มีการขึ้นโครงกระดูกแล้วในไปป์ไลน์หรือเครื่องมือ DCC ของคุณเองได้

ผลลัพธ์คือคลิปการเคลื่อนไหวแบบสแตนด์อโลน ไม่จำเป็นต้องมีโมเดลตัวละคร และไม่ได้ผูกติดกับโมเดลใด ๆ หากต้องการขึ้นโครงกระดูกตัวละครก่อน โปรดดู Rigging API หากต้องการนำคลิปไปใช้กับตัวละครที่มีการขึ้นโครงกระดูกแล้ว ให้ส่ง id ของงานเป็น motion_task_id ไปยัง Animation API

POST/openapi/v1/text-to-motion

สร้างงาน Text to Motion

สร้างงาน Text to Motion ซึ่งสร้างคลิปการเคลื่อนไหวจาก prompt ที่เป็นข้อความ

งานนี้ทำงานอยู่เบื้องหลัง สำหรับระยะเวลาที่งานมักใช้ ดูที่ เวลาในการประมวลผล

งาน prime มีค่าใช้จ่าย 10 เครดิต และใช้โมเดลการเคลื่อนไหวคุณภาพสูงกว่าของ Meshy งาน swift มีค่าใช้จ่าย 3 เครดิต และใช้โมเดลการเคลื่อนไหวที่เร็วกว่าและต้นทุนต่ำกว่า

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

พารามิเตอร์

Name
prompt
Type
string
จำเป็น
Description
ข้อความที่อธิบายการเคลื่อนไหวที่ต้องการสร้าง สูงสุด 400 ตัวอักษร ข้อความที่ยาวกว่านี้จะส่งคืน 400
Name
mode
Type
string
ค่าเริ่มต้น prime
Description
โมเดลการเคลื่อนไหว ซึ่งกำหนดรูปแบบไฟล์ของคลิปด้วย
ค่าที่ใช้ได้:
- prime: คุณภาพสูงกว่า ส่งคืนคลิป FBX
- swift: เร็วกว่าและราคาถูกกว่า ส่งคืนคลิป BVH
ค่าอื่นใดนอกเหนือจากนี้จะส่งคืน 400
Name
duration
Type
number
จำเป็น
Description
ความยาวของคลิปที่ต้องการเป็นวินาที ตั้งแต่ 2 ถึง 10 โดยเพิ่มทีละ 0.5 เช่น 2, 2.5, หรือ 3 ค่าอื่นใดนอกเหนือจากนี้จะส่งคืน 400

ผลลัพธ์ที่ส่งคืน

ฟิลด์ result ของการตอบกลับเก็บ ID ของงาน Text to Motion ใหม่

รูปแบบความล้มเหลว

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะบอกว่าพบปัญหาใด ตัวอย่างเช่น:
- ไม่มี prompt หรือ prompt ว่างเปล่า: prompt หายไป ว่างเปล่า หรือยาวเกิน 400 ตัวอักษร
- mode ไม่ถูกต้อง: mode ไม่ใช่ prime หรือ swift
- duration ไม่ถูกต้อง: duration หายไป อยู่นอกช่วง 2 ถึง 10 หรือไม่ได้เพิ่มทีละ 0.5 วินาที
แก้ไขคำขอแล้วส่งอีกครั้ง ดูที่ ข้อผิดพลาด
Name
401 - Unauthorized
Description
API คีย์หายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
ตัวอย่างเช่น:
- เครดิตไม่เพียงพอ: บัญชีมีเครดิตไม่เพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว ตรวจสอบยอดคงเหลือเครดิตของคุณ แล้วลองใหม่
- แผนฟรี: การสร้างงานต้องใช้แผนที่เสียค่าใช้จ่าย อัปเกรดแผนของคุณในการตั้งค่าการสมัครสมาชิก แล้วลองใหม่
Name
403 - Forbidden
Description
การควบคุมเนื้อหา (moderation) ตรวจพบ prompt นี้ เปลี่ยน prompt แล้วส่งคำขออีกครั้ง
Name
429 - Too Many Requests
Description
คุณเกินการจำกัดอัตราแล้ว รอสักครู่แล้วลองใหม่ ดูที่ การจำกัดอัตรา

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

ดึงข้อมูลงาน Text to Motion

ส่งคืนงาน Text to Motion ตาม ID ของงานนั้น

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
}

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานจากการตอบกลับตอนสร้างงาน

สิ่งที่ส่งคืน

อ็อบเจกต์งาน Text to Motion

GET/openapi/v1/text-to-motion

รายการงาน Text to Motion

คืนค่ารายการงาน Text to Motion ของคุณแบบแบ่งหน้า เรียงจากใหม่ไปเก่า หากต้องการเลื่อนดูรายการ ให้ใช้ page_num และ page_size

การตอบกลับเป็นอาร์เรย์ของ ออบเจกต์งาน Text to Motion

งานที่คุณสร้างผ่าน API จะอยู่ใน API เท่านั้น และจะไม่ปรากฏใน My Assets ในเว็บแอป หากต้องการค้นหางานที่คุณไม่มี 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

สตรีมงาน Text to Motion

สตรีมการอัปเดตของงาน Text to Motion ในรูปแบบ 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
}

พารามิเตอร์

Name
id
Type
path
Description
รหัสงานจากการตอบกลับตอนสร้าง

ผลลัพธ์ที่ได้

สตรีมของอ็อบเจ็กต์งาน Text to Motion ในรูปแบบ Server-Sent Events

ทุก event ประเภท message จะมีอ็อบเจ็กต์งานฉบับเต็มแนบมาด้วย ในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ result จะว่างเปล่า ("" หรือ 0) และ finished_at กับ expires_at จะเป็น 0 หากต้องการติดตามความคืบหน้าของงาน ให้สังเกตที่ status และ progress

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

ลบงาน Text to Motion

ลบงาน Text to Motion อย่างถาวร รวมถึงคลิปโมชันของงานนั้นด้วย คุณไม่สามารถยกเลิกการลบได้

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

Path parameters

Name
id
Type
path
Description
ID ของงานที่ต้องการลบ

สถานะของงาน

การลบงานที่มีสถานะ PENDING จะคืนเครดิตที่ใช้ไปตอนสร้างงานนั้น

งานที่มีสถานะ IN_PROGRESS ไม่สามารถลบได้ คำขอจะคืนค่า 409 Conflict และงานจะยังคงทำงานต่อไป Meshy จะไม่คืนเครดิตให้กับงานที่เริ่มทำงานไปแล้ว ดังนั้นการลบงานนั้นจะทำให้คุณเสียทั้งเครดิตและผลลัพธ์ ให้รอจนกว่างานจะ มีสถานะเป็น SUCCEEDED, FAILED หรือ CANCELED แล้วจึงค่อยลบ

การลบงานที่มีสถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) จะไม่คืนเครดิตให้

ค่าที่ส่งกลับ

200 OK เมื่อลบงานสำเร็จ หรือ 409 Conflict เมื่องานมีสถานะเป็น IN_PROGRESS

อ็อบเจกต์งาน Text to Motion

อ็อบเจกต์งาน Text to Motion อธิบายการสร้างคลิปการเคลื่อนไหวหนึ่งคลิป โดยเก็บสถานะ progress และคลิปเมื่องานสำเร็จ

คุณสมบัติ

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
รหัสของงาน ให้ถือว่าเป็นสตริงทึบ และอย่าพึ่งพารูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งเป็น text-to-motion เสมอ
Name
status
Type
string
Description
สถานะของงาน ซึ่งเป็นหนึ่งใน PENDING, IN_PROGRESS, SUCCEEDED, FAILED, หรือ CANCELED
Name
progress
Type
integer
Description
งานเสร็จไปแล้วเท่าใด แสดงเป็นเปอร์เซ็นต์ตั้งแต่ 0 ถึง 100
Name
created_at
Type
timestamp
Description
เวลาที่สร้างงาน หน่วยเป็นมิลลิวินาทีแบบ Unix
Name
started_at
Type
timestamp
Description
เวลาที่งานเริ่มต้น หน่วยเป็นมิลลิวินาทีแบบ Unix ค่าจะเป็น 0 จนกว่างานจะเริ่ม
Name
finished_at
Type
timestamp
Description
เวลาที่งานเสร็จสิ้น หน่วยเป็นมิลลิวินาทีแบบ Unix ค่าจะเป็น 0 จนกว่างานจะเสร็จสิ้น
Name
expires_at
Type
timestamp
Description
เวลาที่ไฟล์ผลลัพธ์ของงานหมดอายุ หน่วยเป็นมิลลิวินาทีแบบ Unix ค่าจะเป็น 0 จนกว่างานจะเสร็จสิ้น Meshy เก็บคลิปไว้ 3 วันหลังจากงานเสร็จสิ้น ดังนั้นควรดาวน์โหลดก่อนถึงเวลานั้น
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่อยู่ก่อนหน้างานนี้ในคิว ค่านี้มีความหมายเฉพาะตอนที่งานอยู่ในสถานะ PENDING เท่านั้น ฟิลด์นี้จะถูกละไว้เมื่อค่าเป็น 0
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่งานนี้ใช้ไป 10 สำหรับ mode prime หรือ 3 สำหรับ mode swift ค่าจะเป็น 0 สำหรับงานที่ FAILED เพราะ Meshy จะคืนเครดิตเมื่องานล้มเหลว
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดเมื่องานล้มเหลว และเป็น null ในกรณีอื่น ดูที่ ข้อผิดพลาด
Name
result
Type
object
Description
คลิปการเคลื่อนไหวที่สร้างขึ้นเมื่องานสำเร็จ ก่อนหน้านั้น ฟิลด์เหล่านี้จะมีอยู่แต่ว่างเปล่า ("" หรือ 0)
- Name
  motion_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดคลิปการเคลื่อนไหว Meshy จะเซ็น URL ใหม่ทุกครั้งที่มีการอ่าน และ URL จะหมดอายุตามช่วงเวลาที่เก็บรักษาของงาน
- Name
  motion_format
  Type
  string
  Description
  รูปแบบไฟล์ของคลิป fbx สำหรับ mode prime หรือ bvh สำหรับ mode swift
- Name
  duration_ms
  Type
  integer
  Description
  ความยาวของคลิป หน่วยเป็นมิลลิวินาที
- Name
  mode
  Type
  string
  Description
  mode ที่ Meshy ใช้ในการสร้างคลิป prime หรือ swift