API แอนิเมชัน

Endpoint สำหรับค้นหาแอนิเมชันที่พร้อมใช้งาน และนำไปใช้กับตัวละครที่มีการทำ rig ไว้แล้ว

POST/openapi/v1/animations

Create an Animation Task

เอนด์พอยต์นี้ช่วยให้คุณสร้างงานใหม่เพื่อนำแอนิเมชันไปใช้กับตัวละครที่ผ่านการทำ rigging มาแล้ว — ไม่ว่าจะเป็นแอ็กชันสำเร็จรูปจากคลังแอนิเมชัน (action_id) หรือคลิปการเคลื่อนไหวที่คุณสร้างขึ้นด้วย Text to Motion API (motion_task_id) รองรับตัวเลือกการประมวลผลภายหลังด้วย

พารามิเตอร์

Name
rig_task_id
Type
string
จำเป็น
Description
id ของงาน rigging ที่เสร็จสมบูรณ์แล้ว (จาก POST /openapi/v1/rigging) ตัวละครจากงานนี้จะถูกนำไปทำแอนิเมชัน
Name
action_id
Type
integer
Description
รหัสระบุแอ็กชันแอนิเมชันสำเร็จรูปที่จะนำไปใช้ ดูรายการแอนิเมชันที่มีทั้งหมดได้ที่ Animation Library Reference โปรดระบุ action_id หรือ motion_task_id อย่างใดอย่างหนึ่งเท่านั้น
Name
motion_task_id
Type
string
Description
id ของงาน Text to Motion ที่เสร็จสมบูรณ์แล้ว เพื่อนำมาใช้แทนแอ็กชันสำเร็จรูป คลิปที่สร้างขึ้นจะถูก retarget ไปยังตัวละครที่ทำ rigging แล้ว และคลิปจะถูกบันทึกสแนปช็อตไว้ ณ เวลาที่สร้าง ดังนั้นงานนี้จะไม่ได้รับผลกระทบหากงานต้นทางหมดอายุหรือถูกลบในภายหลัง อย่างไรก็ตาม แอสเซตของงานต้นทางจะถูกเก็บไว้เพียง 3 วัน — โปรดนำคลิปไปใช้ก่อนที่จะหมดอายุ ต้องใช้กับ rig แบบสองขา (biped) เท่านั้น โปรดระบุ action_id หรือ motion_task_id อย่างใดอย่างหนึ่งเท่านั้น
Name
post_process
Type
object
Description
การประมวลผลภายหลัง (ไม่บังคับ) สำหรับผลลัพธ์แอนิเมชัน หากไม่ระบุ คุณจะได้รับไฟล์แอนิเมชันมาตรฐาน

ใช้เฉพาะเมื่อ post_process is set

Name
operation_type
Type
string
จำเป็น
Description
ประเภทของการดำเนินการที่จะทำ ค่าที่ใช้ได้: change_fps, fbx2usdz, extract_armature
Name
fps
Type
integer
ค่าเริ่มต้น 30
Description
อัตราเฟรมเป้าหมาย ใช้ได้เฉพาะเมื่อ operation_type เป็น change_fps ค่าที่อนุญาต: 24, 25, 30, 60

เมื่อใช้ motion_task_id การ retarget อาจสร้างแอนิเมชันที่มีเฉพาะไฟล์ GLB เท่านั้น หากคุณระบุ post_process ไว้แต่ไม่มีไฟล์ FBX ให้ใช้ งานจะล้มเหลวพร้อมข้อผิดพลาด task_error และเครดิตของคุณจะถูกคืนโดยอัตโนมัติ แต่หากไม่ได้ระบุ post_process งานจะสำเร็จและ animation_fbx_url จะเป็นค่าว่าง

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

พร็อพเพอร์ตี้ result ในการตอบกลับจะมี id ของงานแอนิเมชันที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- ขาดพารามิเตอร์: ไม่มี rig_task_id หรือไม่มีทั้ง action_id และ motion_task_id
- พารามิเตอร์ขัดแย้งกัน: มีการระบุทั้ง action_id และ motion_task_id — ทั้งสองใช้ร่วมกันไม่ได้
- rig task ไม่ถูกต้อง: rig_task_id ไม่ถูกต้อง หรืออ้างอิงถึงงานที่ล้มเหลว/ไม่มีอยู่จริง
- action ID ไม่ถูกต้อง: action_id ไม่ตรงกับแอนิเมชันที่ใช้งานได้จริง
- motion task ยังไม่พร้อม: งาน motion_task_id ยังไม่มีสถานะ SUCCEEDED
- rig ไม่รองรับ: motion_task_id ต้องใช้กับ rig แบบสองขา (biped) เท่านั้น rig แบบสี่ขา (quadruped) จะถูกปฏิเสธ
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้
Name
404 - Not Found
Description
ไม่พบงาน rigging ที่ระบุด้วย rig_task_id หรือไม่พบงาน motion ที่ระบุด้วย motion_task_id หรือคลิปการเคลื่อนไหวหมดอายุแล้ว (แอสเซตของงานต้นทางจะถูกเก็บไว้เพียง 3 วัน)
Name
429 - Too Many Requests
Description
คุณส่งคำขอเกินขีดจำกัดอัตราที่กำหนดไว้

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

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

GET/openapi/v1/animations/:id

เรียกดูงานแอนิเมชัน

เอนด์พอยต์นี้ช่วยให้คุณเรียกดูงานแอนิเมชันได้โดยระบุ id ของงานที่ถูกต้อง ดูรายละเอียดคุณสมบัติที่มีอยู่ได้ที่ The Animation Task Object

พารามิเตอร์

Name
id
Type
path
Description
รหัสเฉพาะสำหรับงานแอนิเมชันที่ต้องการเรียกดู

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

การตอบกลับจะมีอ็อบเจ็กต์ Animation Task รวมอยู่ด้วย ดูรายละเอียดได้ในหัวข้อ The Animation Task Object

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/animations/:id

ลบงานแอนิเมชัน

เอนด์พอยต์นี้จะลบงานแอนิเมชันอย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดที่เกี่ยวข้อง การกระทำนี้ไม่สามารถย้อนกลับได้

Path Parameters

Name
id
Type
path
Description
ID ของงานแอนิเมชันที่ต้องการลบ

Returns

ส่งคืน 200 OK เมื่อสำเร็จ

Request

DELETE

/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/animations

List Animation Tasks

ส่งคืนรายการงานแอนิเมชันของผู้เรียกใช้แบบแบ่งหน้า โดยเรียงจากล่าสุดไปเก่าสุด ใช้การแบ่งหน้ามาตรฐานผ่าน page_num และ page_size

โปรดทราบว่างานที่สร้างผ่าน API จะถูกจัดการผ่าน API เท่านั้น — งานเหล่านี้จะไม่ปรากฏใน My Assets ของเว็บแอป ใช้เอนด์พอยต์นี้เพื่อค้นหางานที่คุณไม่มี ID อีกต่อไป

Request

GET

/openapi/v1/animations

curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/animations/:id/stream

สตรีมงานแอนิเมชัน

เอนด์พอยต์นี้จะสตรีมข้อมูลอัปเดตแบบเรียลไทม์สำหรับงานแอนิเมชันโดยใช้ Server-Sent Events (SSE)

พารามิเตอร์

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

สิ่งที่ส่งกลับ

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

สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะรวมเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/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 event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

The Animation Task Object

Animation Task object แสดงถึงหน่วยงานสำหรับการนำแอนิเมชันไปใช้กับตัวละครที่มีการทำริกไว้แล้ว

คุณสมบัติ

Name
id
Type
string
Description
รหัสเฉพาะสำหรับงานนี้
Name
type
Type
string
Description
ประเภทของงานแอนิเมชัน ค่าคือ animate
Name
status
Type
string
Description
สถานะของงาน ค่าที่เป็นไปได้: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
progress ของงาน (0-100)
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีนับตั้งแต่ epoch) เมื่อสร้างงานนี้ขึ้น
ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 น. GMT จะแสดงเป็น 1693569600000 สิ่งนี้ใช้กับไทม์สแตมป์ ทั้งหมด ใน Meshy API
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีนับตั้งแต่ epoch) เมื่องานเริ่มดำเนินการ เป็น 0 หากยังไม่เริ่ม
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีนับตั้งแต่ epoch) เมื่องานเสร็จสิ้น เป็น 0 หากยังไม่เสร็จสิ้น
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีนับตั้งแต่ epoch) เมื่อสินทรัพย์ผลลัพธ์ของงานหมดอายุ
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับงานที่ล้มเหลว ดู ข้อผิดพลาด สำหรับการอ้างอิงออบเจ็กต์ task_error แบบเต็ม
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกใช้ไปกับงานนี้ จะปรากฏเมื่อสถานะของงานเป็น PENDING, IN_PROGRESS หรือ SUCCEEDED จะคืนค่า 0 สำหรับงานที่ FAILED (เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)
Name
result
Type
object
Description
มี URL ของแอนิเมชันผลลัพธ์หากงานมีสถานะ SUCCEEDED
- Name
  animation_glb_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันในรูปแบบ GLB
- Name
  animation_fbx_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันในรูปแบบ FBX
- Name
  processed_usdz_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันที่ผ่านการประมวลผลในรูปแบบ USDZ
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดอาร์เมเจอร์ที่ผ่านการประมวลผลในรูปแบบ FBX
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันที่มีการเปลี่ยนแปลง FPS ในรูปแบบ FBX (เช่น หากมีการใช้การดำเนินการ change_fps)
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่อยู่ก่อนหน้าในคิว มีความหมายเฉพาะเมื่อสถานะเป็น PENDING เท่านั้น

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}