Text to Motion API

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

ผลลัพธ์เป็นคลิปการเคลื่อนไหวแบบเดี่ยว: โดยไม่ต้องการและไม่ติดกับโมเดลตัวละคร หากต้องการ rig ตัวละครก่อน ดูที่ Rigging API.

POST/openapi/v1/text-to-motion

สร้างงาน Text to Motion

เอนด์พอยต์นี้จะสร้างงานใหม่เพื่อสร้างคลิปการเคลื่อนไหวจาก prompt ข้อความ

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

พารามิเตอร์

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

ผลลัพธ์

คุณสมบัติ result ของการตอบกลับจะมี id ของงาน Text to Motion ที่สร้างใหม่

โหมดความล้มเหลว

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

Request

POST

/openapi/v1/text-to-motion

# สร้างคลิปการเคลื่อนไหวเฉพาะพารามิเตอร์ที่ต้องการเท่านั้น
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
  }'

# สร้างคลิปรวดเร็วและประหยัดด้วยโหมด 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
  }'

Response

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

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

เรียกดูงานข้อความไปยังการเคลื่อนไหว

เอนด์พอยต์นี้อนุญาตให้คุณเรียกดูงานข้อความไปยังการเคลื่อนไหว โดยให้รหัส id ที่ถูกต้อง อ้างอิงเพื่อดู วัตถุของงานข้อความไปยังการเคลื่อนไหว เพื่อดูคุณสมบัติที่รวมเข้ามา

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงานข้อความไปยังการเคลื่อนไหวที่จะเรียกดู

ส่งคืน

การตอบสนองจะมีวัตถุงานข้อความไปยังการเคลื่อนไหว ตรวจสอบส่วน วัตถุของงานข้อความไปยังการเคลื่อนไหว เพื่อดูรายละเอียด

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

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

ส่งคืนรายการที่ถูกแบ่งหน้าของงาน Text to Motion ของผู้เรียก, โดยเรียงลำดับจากใหม่สุดก่อน. การแบ่งหน้ามาตรฐานผ่าน page_num และ page_size.

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

โปรดทราบว่างานที่สร้างผ่าน API จะถูกจัดการผ่าน API — พวกมันจะไม่แสดงในส่วน My Assets ของเว็บแอป. ใช้ endpoint นี้ในการค้นหางานที่คุณไม่มี 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)

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน Text to Motion ที่จะสตรีม

ผลลัพธ์

ส่งคืนสตรีมของ วัตถุงาน Text to Motion เป็น Server-Sent Events

ทุกเหตุการณ์ message จะแบกวัตถุงานทั้งหมด ขณะที่งานอยู่ในสถานะ PENDING หรือ IN_PROGRESS, ฟิลด์ result จะยังคงว่างเปล่า ("" / 0) และ finished_at / expires_at คือ 0; ติดตามดู status และ 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

// ตัวอย่างเหตุการณ์ข้อผิดพลาด
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// เหตุการณ์ข้อความแบกวัตถุงานทั้งหมดในแต่ละช่วง; ฟิลด์ผลลัพธ์ยังคงว่างเปล่าจนกว่างานจะสำเร็จ
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: { // ตัวอย่างของรายการสตรีมงานที่สำเร็จ, สะท้อนถึงโครงสร้าง 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
}

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

ลบงาน Text to Motion

เอนด์พอยต์นี้จะลบงาน Text to Motion อย่างถาวร รวมถึงคลิปเคลื่อนไหวที่สร้างขึ้น การดำเนินการนี้ไม่สามารถย้อนกลับได้

พารามิเตอร์ในเส้นทาง

Name
id
Type
path
Description
ID ของงาน Text to Motion ที่จะลบ

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

ส่งกลับ 200 OK เมื่อดำเนินการสำเร็จ

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.

วัตถุภารกิจข้อความเป็นการเคลื่อนไหว

วัตถุภารกิจข้อความเป็นการเคลื่อนไหวแสดงงานที่ใช้สำหรับสร้างคลิปการเคลื่อนไหวจากข้อความ prompt

คุณสมบัติ

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
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อตอนที่ภารกิจถูกสร้างขึ้น
ไทม์สแตมป์แสดงจำนวนมิลลิวินาทีที่ผ่านมาตั้งแต่ 1 มกราคม 1970 UTC ตาม มาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 GMT จะแสดงเป็น 1693569600000 สิ่งนี้นำไปใช้กับ ทั้งหมด ของไทม์สแตมป์ใน Meshy API
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อตอนที่ภารกิจเริ่มกระบวนการ 0 ถ้ายังไม่เริ่ม
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อตอนที่ภารกิจสิ้นสุด 0 ถ้ายังไม่สิ้นสุด
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อตอนที่ผลลัพธ์ของภารกิจหมดอายุ 0 จนกว่าภารกิจจะสิ้นสุด คลิปที่สร้างขึ้นจะถูกเก็บไว้เป็นเวลา 3 วันหลังจากภารกิจสิ้นสุด; ดาวน์โหลดก่อนที่จะหมดอายุ
Name
preceding_tasks
Type
integer
Description
จำนวนของภารกิจก่อนหน้าในคิว มีความหมายเฉพาะเมื่อสถานะคือ PENDING; อ้างถึงไม่ได้เมื่อเป็นศูนย์
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกใช้ไปกับภารกิจนี้ 10 สำหรับโหมด prime, 3 สำหรับโหมด swift, จะกลับมาเป็น 0 สำหรับภารกิจที่ FAILED (เครดิตจะถูกคืนในกรณีที่ล้มเหลว)
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับภารกิจที่ล้มเหลว; null นอกจากภารกิจ FAILED ดู ข้อผิดพลาด สำหรับการอ้างอิงวัตถุ task_error เต็มรูปแบบ
Name
result
Type
object
Description
บรรจุคลิปการเคลื่อนไหวที่สร้างขึ้นเมื่อภารกิจ SUCCEEDED; จนถึงตอนนั้นฟิลด์จะปรากฏแต่จะว่างเปล่า ("" / 0)
- Name
  motion_url
  Type
  string
  Description
  URL ที่ดาวน์โหลดได้สำหรับคลิปการเคลื่อนไหวที่สร้างขึ้น URL จะถูกลงนามใหม่ทุกครั้งที่อ่านและจะหมดอายุพร้อมกับช่วงการเก็บรักษาของภารกิจ
- Name
  motion_format
  Type
  string
  Description
  รูปแบบไฟล์ของคลิป: fbx สำหรับโหมด prime, bvh สำหรับโหมด swift
- Name
  duration_ms
  Type
  integer
  Description
  ระยะเวลาของคลิปที่สร้างขึ้นในหน่วยมิลลิวินาที
- Name
  mode
  Type
  string
  Description
  โหมดที่คลิปถูกสร้างขึ้น: prime หรือ 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
}