Animation API

นำแอนิเมชันไปใช้กับตัวละครที่มี rig และแสดงรายการแอนิเมชันที่คุณสามารถนำไปใช้ได้

POST/openapi/v1/animations

สร้างงาน Animation

สร้างงาน Animation ซึ่งนำแอนิเมชันไปใช้กับตัวละครที่คุณ rigging ไว้ก่อนหน้านี้ แอนิเมชันสามารถเป็นหนึ่งในตัวเลือกต่อไปนี้:

ท่าแอนิเมชันสำเร็จรูปจากคลังแอนิเมชัน (action_id)
ท่าแอนิเมชันสำเร็จรูปหลายท่ารวมกันเป็นไฟล์เดียว (action_ids)
คลิปการเคลื่อนไหวที่คุณสร้างด้วย Text to Motion API (motion_task_id)

คุณยังสามารถประมวลผลผลลัพธ์เพิ่มเติม (post-process) ได้ งานนี้จะทำงานในเบื้องหลัง สำหรับระยะเวลาที่งานมักใช้ ดูที่ เวลาในการประมวลผล

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 several preset actions and get one file with one clip per 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",
    "action_ids": [10, 25, 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"
}

พารามิเตอร์

Name
rig_task_id
Type
string
จำเป็น
Description
ID ของงาน Rigging ที่มีตัวละครที่จะนำมาสร้างแอนิเมชัน ได้จาก POST /openapi/v1/rigging งานนั้นต้องมีสถานะเป็น SUCCEEDED

ส่งค่าเพียงอย่างใดอย่างหนึ่งจาก action_id, action_ids, และ motion_task_id

Name
action_id
Type
integer
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณส่ง action_ids หรือ motion_task_id ID ของแอนิเมชันสำเร็จรูปที่จะนำไปใช้ สำหรับรายการแอนิเมชันทั้งหมด ดูที่ เอกสารอ้างอิงคลังแอนิเมชัน หรือ รายการแอนิเมชัน

Name
action_ids
Type
array of integers
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณส่ง action_id หรือ motion_task_id ID ของแอนิเมชันสำเร็จรูปตั้งแต่ 1 ถึง 10 รายการที่จะนำไปใช้พร้อมกัน โดยห้ามซ้ำกัน หากมี ID มากกว่า 10 รายการ หรือมี ID ซ้ำกัน จะได้รับการตอบกลับ 400 สำหรับ ID ทั้งหมด ดูที่ เอกสารอ้างอิงคลังแอนิเมชัน
Meshy จะส่งคืนไฟล์หนึ่งไฟล์ที่มีคลิปแอนิเมชันหนึ่งคลิปต่อหนึ่ง action ซึ่งเหมาะสำหรับ state machine ในเกมเอนจิน Meshy คิดค่าใช้จ่ายสำหรับแต่ละ action ในรายการ ดูที่ ราคา
รายการที่มี ID เพียงรายการเดียวทำงานเหมือนกับการส่ง ID นั้นเป็น action_id

Name
motion_task_id
Type
string
จำเป็น
Description
จำเป็นต้องระบุ เว้นแต่คุณส่ง action_id หรือ action_ids ID ของงาน Text to Motion ที่มีคลิปที่จะนำมาใช้แทนท่าสำเร็จรูป งานนั้นต้องมีสถานะเป็น SUCCEEDED และ rig ต้องเป็นแบบสองขา (biped)
Meshy จะ retarget คลิปไปยังตัวละครที่ rig ไว้ โดยจะคัดลอกคลิปทันทีที่คุณสร้างงานนี้ ดังนั้นงานนี้จะไม่ได้รับผลกระทบหากต่อมางาน Text to Motion หมดอายุหรือคุณลบงานนั้นไป Meshy จะเก็บไฟล์ของงาน Text to Motion ไว้ 3 วัน ดังนั้นควรนำคลิปไปใช้ก่อนเวลานั้น

Name
post_process
Type
object
Description
การประมวลผลเพิ่มเติมสำหรับผลลัพธ์แอนิเมชัน ละไว้หากต้องการไฟล์แอนิเมชันมาตรฐาน
เมื่อใช้ motion_task_id การ retarget อาจได้ผลลัพธ์เป็นแอนิเมชันแบบ GLB เท่านั้น หากคุณส่ง post_process แต่ไม่มีไฟล์ FBX ให้ใช้ งานจะล้มเหลวพร้อม task_error และ Meshy จะคืนเครดิตให้คุณ หากไม่ส่ง post_process งานจะสำเร็จ และ animation_fbx_url จะเป็นค่าว่าง

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

Name
operation_type
Type
string
Description
การดำเนินการที่จะรัน หากไม่ระบุ Meshy จะไม่สร้างไฟล์เพิ่มเติม ค่าที่ไม่อยู่ในรายการต่อไปนี้จะได้รับการตอบกลับ 400
ค่าที่ใช้ได้:
- change_fps: เปลี่ยนอัตราเฟรมเป็น fps
- fbx2usdz: แปลงแอนิเมชันเป็น USDZ
- extract_armature: แยกอาร์เมเจอร์ออกมาเป็นไฟล์ FBX
Name
fps
Type
integer
ค่าเริ่มต้น 30
Description
อัตราเฟรมที่จะเปลี่ยนเป็น หนึ่งใน 24, 25, 30, หรือ 60 ใช้ได้เฉพาะเมื่อ operation_type เป็น change_fps ค่าอื่นนอกเหนือจากนี้จะได้รับการตอบกลับ 400

เมื่อใช้ action_ids งานจะส่งคืนไฟล์รวมหนึ่งไฟล์แทนที่จะเป็นไฟล์แยกต่อ action animation_glb_url และ animation_fbx_url แต่ละรายการจะชี้ไปยังไฟล์หนึ่งไฟล์ที่เก็บทุก action ที่ร้องขอไว้เป็นคลิปแยกกัน ในไฟล์นั้น:

ลำดับคลิป: เรียงตามลำดับของอาร์เรย์ action_ids ไม่ใช่ลำดับตัวเลขของ ID
ชื่อคลิป: ชื่อของแอนิเมชันในคลัง ชื่อเหล่านี้ตรงกับชื่อที่คุณจะได้รับเมื่อส่งออกแอนิเมชันทั้งหมดของตัวละครเป็นไฟล์เดียวจากเว็บแอป Meshy หากมี ID ที่ร้องขอสองรายการมีชื่อคลิปเดียวกัน Meshy จะเพิ่ม action_id ต่อท้ายรายการหลังเพื่อให้ชื่อไม่ซ้ำกัน
การประมวลผลเพิ่มเติม: Meshy จะนำไปใช้กับไฟล์ที่รวมแล้ว ไม่ใช่กับแต่ละคลิป

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

ฟิลด์ result ของการตอบกลับจะมี ID ของงาน Animation ใหม่

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด ตัวอย่างเช่น:
- ขาดพารามิเตอร์: ไม่มี rig_task_id หรือไม่มีการส่ง action_id, action_ids, หรือ motion_task_id เลย
- พารามิเตอร์ขัดแย้งกัน: คำขอมีมากกว่าหนึ่งรายการจาก action_id, action_ids, และ motion_task_id ให้ส่งเพียงอย่างเดียว
- งาน rig ไม่ถูกต้อง: rig_task_id ไม่ใช่ ID งานที่ถูกต้อง ไม่ใช่งาน Rigging หรือชี้ไปยังงานที่ยังไม่สำเร็จ
- ID action ไม่ถูกต้อง: action_id หรือรายการใน action_ids ไม่ใช่แอนิเมชันที่ถูกต้อง
- มี action มากเกินไป: action_ids มีมากกว่า 10 ID
- action ซ้ำกัน: action_ids มี ID เดียวกันซ้ำกันมากกว่าหนึ่งครั้ง
- งาน motion ยังไม่พร้อม: งาน motion_task_id ยังไม่มีสถานะ SUCCEEDED
- rig ไม่รองรับ: motion_task_id ต้องใช้ rig แบบสองขา (biped) และ Meshy จะปฏิเสธ rig แบบสี่ขา (quadruped)
แก้ไขคำขอแล้วส่งอีกครั้ง ดูที่ ข้อผิดพลาด
Name
401 - Unauthorized
Description
ไม่มี API คีย์หรือ API คีย์ไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
ตัวอย่างเช่น:
- เครดิตไม่เพียงพอ: บัญชีมีเครดิตไม่เพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว ตรวจสอบยอดเครดิตคงเหลือของคุณแล้วลองใหม่
- แผนฟรี: การสร้างงานต้องใช้แผนแบบชำระเงิน อัปเกรดแผนของคุณในการตั้งค่าการสมัครสมาชิก แล้วลองใหม่
Name
403 - Forbidden
Description
งาน rig_task_id เป็นโมเดลแบบนูนต่ำ (bas-relief) ซึ่งเอนด์พอยต์นี้ไม่สามารถสร้างแอนิเมชันได้ ข้อความคือ This model type does not support this operation ให้ rig โมเดลอื่นแทน
Name
404 - Not Found
Description
Meshy ไม่พบงานหรือไฟล์ที่คำขอต้องการ หนึ่งในกรณีต่อไปนี้:
- Meshy ไม่พบงาน rig_task_id ในงานของคุณ ตรวจสอบ ID
- Meshy ลบไฟล์ของงาน rig_task_id หลังจาก expires_at ให้ rig ตัวละครอีกครั้ง
- Meshy ไม่พบงาน motion_task_id ตรวจสอบ ID
- คลิปการเคลื่อนไหวหมดอายุแล้ว เนื่องจาก Meshy เก็บไฟล์ของงาน Text to Motion ไว้ 3 วัน ให้สร้างงาน Text to Motion ใหม่
Name
429 - Too Many Requests
Description
คุณเกินการจำกัดอัตราที่กำหนดไว้ กรุณารอแล้วลองใหม่ ดูที่ การจำกัดอัตรา

GET/openapi/v1/animations/:id

ดึงข้อมูลงานแอนิเมชัน

ส่งคืนงานแอนิเมชันตามรหัส (ID) ของงานนั้น

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": null,
  "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=..."
  }
}

พารามิเตอร์

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

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

อ็อบเจ็กต์งานแอนิเมชัน

DELETE/openapi/v1/animations/:id

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

ลบงานแอนิเมชันอย่างถาวร รวมถึงโมเดลและข้อมูลของงานนั้น คุณไม่สามารถยกเลิกการลบได้

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

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

พารามิเตอร์พาธ

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

สถานะงาน

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

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

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

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

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

GET/openapi/v1/animations

List Animation tasks

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

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

สตรีมงาน Animation

สตรีมการอัปเดตของงาน Animation ในรูปแบบ Server-Sent Events (SSE)

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.
// These examples are shortened. Each event holds the full task object.
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, with the same structure as the 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": null,
  "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?..."
  }
}

พารามิเตอร์

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

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

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

แต่ละอีเวนต์จะมีออบเจ็กต์งานฉบับเต็ม ในรูปแบบเดียวกับที่เอนด์พอยต์ Get ส่งคืน ในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์ของงานจะยังไม่มีค่า

The Animation task object

Animation task object อธิบายแอนิเมชันหนึ่งรายการที่นำไปใช้กับตัวละครที่มีการ rig แล้ว โดยจะเก็บสถานะ progress และไฟล์แอนิเมชันเมื่องานสำเร็จ

Properties

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": null,
  "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?..."
  }
}

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
ระบุว่างานเสร็จไปมากน้อยเพียงใด เป็นเปอร์เซ็นต์ โดยจะเป็น 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
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดเมื่องานล้มเหลว จะเป็น null เว้นแต่สถานะจะเป็น FAILED ดู ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่งานนี้ใช้ไป จะปรากฏเมื่อสถานะเป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED โดยจะเป็น 0 สำหรับงานที่ FAILED เนื่องจาก Meshy จะคืนเครดิตเมื่องานล้มเหลว
Name
result
Type
object
Description
URL สำหรับดาวน์โหลดไฟล์แอนิเมชัน เมื่องานมีสถานะเป็น SUCCEEDED
- Name
  animation_glb_url
  Type
  string
  Description
  แอนิเมชันในรูปแบบไฟล์ GLB สำหรับงานที่สร้างด้วย action_ids ไฟล์เดียวนี้จะเก็บทุกแอ็กชันที่ร้องขอไว้เป็นคลิปแยกกัน
- Name
  animation_fbx_url
  Type
  string
  Description
  แอนิเมชันในรูปแบบไฟล์ FBX สำหรับงานที่สร้างด้วย action_ids ไฟล์เดียวนี้จะเก็บทุกแอ็กชันที่ร้องขอไว้เป็นคลิปแยกกัน
- Name
  processed_usdz_url
  Type
  string
  Description
  แอนิเมชันที่ผ่านการประมวลผลแล้ว ในรูปแบบไฟล์ USDZ
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  อาร์เมเจอร์ที่ผ่านการประมวลผลแล้ว ในรูปแบบไฟล์ FBX
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  แอนิเมชันที่เปลี่ยนอัตราเฟรมแล้ว ในรูปแบบไฟล์ FBX เช่น เมื่อคุณใช้การดำเนินการ change_fps
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่อยู่ก่อนหน้างานนี้ในคิว ค่านี้มีความหมายเฉพาะในขณะที่งานยังเป็น PENDING เท่านั้น ฟิลด์นี้จะถูกตัดออกเมื่อค่าเป็น 0

GET/openapi/v1/animations/library

List animations

คืนค่าแอนิเมชันทุกรายการในคลัง โดยเรียงตาม action_id การตอบกลับเป็นรายการทั้งหมด ไม่มีการแบ่งหน้า ดังนั้นการเรียกเพียงครั้งเดียวก็สามารถใช้เติมตัวเลือกแอ็กชันได้ ตัวกรองจะช่วยจำกัดผลลัพธ์ให้แคบลง หากต้องการแอนิเมชันทั้งหมด ให้ละเว้นตัวกรองทั้งหมดไป

หากต้องการเรียกดูรายการเดียวกันพร้อมตัวอย่างแอนิเมชันของแต่ละแอ็กชัน โปรดดูที่ เอกสารอ้างอิงคลังแอนิเมชัน

คำขอนี้ไม่เสียเครดิต

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

พารามิเตอร์

Name
search
Type
string
Description
ข้อความที่ต้องการค้นหา Meshy จะคืนค่าแอนิเมชันที่มี name หรือ key ที่มีข้อความนี้อยู่ โดยไม่สนใจตัวพิมพ์เล็ก-ใหญ่ Meshy จะจับคู่ข้อความแบบตรงตัวอักษร ดังนั้น % และ _ จึงไม่ใช่ไวลด์การ์ด
Name
category
Type
string
Description
หมวดหมู่ที่ต้องการแสดงรายการ โดยต้องตรงกันแบบทุกตัวอักษร หากเป็นหมวดหมู่ที่ไม่รู้จักจะได้ผลลัพธ์เป็นรายการว่าง
ค่าที่ใช้ได้:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
หมวดหมู่ย่อยที่ต้องการแสดงรายการ โดยต้องตรงกันแบบทุกตัวอักษร คุณสามารถส่งค่านี้โดยไม่มี category ได้ ชื่อหมวดหมู่ย่อยไม่ได้มีความเป็นเอกลักษณ์ในแต่ละหมวดหมู่ ตัวอย่างเช่น Transitioning อยู่ภายใต้ทั้ง Fighting และ DailyActions ดังนั้นหากไม่มี category ตัวกรองจะจับคู่หมวดหมู่ย่อยนี้ในทุกหมวดหมู่
Name
action_ids
Type
string
Description
แอนิเมชันที่ต้องการให้คืนค่า โดยระบุค่า action_id คั่นด้วยจุลภาคได้สูงสุด 200 ค่า ใช้พารามิเตอร์นี้เพื่อค้นหา ID เฉพาะเจาะจงแทนการเรียกดูทั้งหมด หากระบุเกิน 200 ID จะได้รับการตอบกลับเป็น 400
การตอบกลับจะไม่รวม ID ที่ไม่มีแอนิเมชันใดตรงกัน ดังนั้นคุณยังสามารถใช้ตัวกรองนี้เพื่อตรวจสอบว่า ID ที่คุณจัดเก็บไว้ยังคงใช้งานได้หรือไม่

การใช้ตัวกรองร่วมกัน

Meshy จะใช้ตัวกรองทั้งหมดร่วมกัน แต่ละตัวจะช่วยจำกัดผลลัพธ์ให้แคบลง ดังนั้น Meshy จะคืนค่าแอนิเมชันก็ต่อเมื่อตรงกับตัวกรองทุกตัว ภายในตัวกรองเดียว ค่าใดค่าหนึ่งของตัวกรองนั้นก็สามารถจับคู่ได้ ตัวอย่างเช่น search จะจับคู่กับ name หรือ key และ action_ids จะจับคู่กับ ID ใดก็ได้ในรายการ

ดังนั้นการรวมตัวกรองที่ไม่มีความซ้อนทับกันจะคืนค่าเป็นอาร์เรย์ว่าง ไม่ใช่ข้อผิดพลาด แอ็กชัน 92 คือ "Double Combo Attack" ซึ่งเป็นแอนิเมชันประเภท Fighting ตัวอย่างเช่น:

?action_ids=92&category=Fighting คืนค่าแอ็กชัน 92
?action_ids=92&category=Dancing คืนค่า [] เนื่องจากไม่ใช่แอนิเมชันประเภท Dancing
?action_ids=92&search=walk คืนค่า [] เนื่องจากชื่อของมันไม่ตรงกับ walk

หากต้องการแอนิเมชันเฉพาะเจาะจงในหมวดหมู่ใดก็ได้ ให้ส่ง action_ids เพียงอย่างเดียว

ค่าที่คืนกลับ

รายการอ็อบเจ็กต์แอนิเมชัน

การสร้างงานแอนิเมชัน ยอมรับทุก action_id ที่เอนด์พอยต์นี้คืนค่า และเอนด์พอยต์นี้ก็คืนค่าทุก ID ที่การสร้างงานยอมรับเช่นกัน ทั้งสองส่วนนี้จะไม่รวมแอนิเมชันที่เลิกใช้งานแล้ว หากคุณแคชคลังนี้ไว้ ควรรีเฟรชเป็นระยะ เพื่อไม่ให้ ID ที่เลิกใช้งานแล้วยังคงค้างอยู่ในตัวเลือกของคุณ

ออบเจกต์แอนิเมชัน

ออบเจกต์แอนิเมชันอธิบายแอนิเมชันหนึ่งรายการในไลบรารี

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}

Name
action_id
Type
integer
Description
ค่าที่จะส่งเป็น action_id เมื่อคุณสร้างงานแอนิเมชัน ค่านี้ไม่ซ้ำกันและคงที่ แต่ไม่ต่อเนื่องกัน แอนิเมชันที่ถูกเลิกใช้จะทิ้งช่องว่างไว้ในลำดับเลข ดังนั้นอย่าสันนิษฐานว่าทุก ID ในช่วงหนึ่งจะใช้งานได้
Name
name
Type
string
Description
ชื่อที่ใช้แสดงของแอนิเมชัน ชื่อนี้ไม่ซ้ำกัน เนื่องจากแอนิเมชันบางรายการใช้ชื่อร่วมกับตัวแปรอื่น หากต้องการระบุแอนิเมชันให้ใช้ action_id หรือ key
Name
key
Type
string
Description
สแลก (slug) ที่ไม่ซ้ำกันและคงที่สำหรับแอนิเมชัน ใช้เมื่อคุณต้องการ ID ที่ไม่ใช่ตัวเลขสำหรับใช้เป็นคีย์ในระบบจัดเก็บข้อมูลของคุณเอง
Name
category
Type
string
Description
กลุ่มระดับบนสุด เช่น Fighting
Name
sub_category
Type
string
Description
กลุ่มย่อยภายในหมวดหมู่ เช่น AttackingwithWeapon
Name
preview_url
Type
string
Description
URL ของตัวอย่าง GIF เคลื่อนไหวของแอ็กชัน คุณสามารถนำไปแสดงได้โดยตรงในตัวเลือกของคุณเอง