Text to Motion API

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

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

POST/openapi/v1/text-to-motion

Create a Text to Motion Task

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

งานนี้ทำงานในเบื้องหลัง หากต้องการทราบว่าโดยปกติใช้เวลานานเท่าใด โปรดดู Processing Times

งานที่มี mode เป็น prime ใช้ 10 เครดิต และสร้างด้วยโมเดลการเคลื่อนไหวคุณภาพสูงสุดของเรา งานที่มี mode เป็น 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 ตัวอักษร
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)

Returns

พร็อพเพอร์ตี้ result ของการตอบกลับประกอบด้วย id ของงาน Text to Motion ที่สร้างขึ้นใหม่

Failure Modes

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

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

เรียกดูงาน Text to Motion

เอนด์พอยต์นี้ช่วยให้คุณสามารถเรียกดูงาน Text to Motion โดยระบุ id ของงานที่ถูกต้อง ดูรายละเอียดคุณสมบัติที่มีอยู่ได้ที่ 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
}

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน Text to Motion ที่ต้องการเรียกดู

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

การตอบกลับจะประกอบด้วยออบเจ็กต์งาน Text to Motion ดูรายละเอียดได้ที่ส่วน The Text to Motion Task Object

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 ของเว็บแอป ใช้เอนด์พอยต์นี้เพื่อค้นหางานที่คุณไม่มี 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 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
}

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน Text to Motion ที่ต้องการสตรีม

สิ่งที่ได้รับกลับมา

ส่งคืนสตรีมของ The Text to Motion Task Objects ในรูปแบบ Server-Sent Events

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

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

ลบ Task การสร้าง Text to Motion

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

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 is left 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 ของ task การสร้าง Text to Motion ที่ต้องการลบ

สถานะของ Task

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

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

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

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

ส่งกลับ 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่อ task อยู่ในสถานะ IN_PROGRESS

The Text to Motion Task Object

Text to Motion Task object แสดงถึงหน่วยงานสำหรับการสร้าง motion clip จาก text prompt

Properties

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