Rigging API

Rigging API ช่วยให้คุณสามารถเพิ่มโครงกระดูก (อาร์เมเจอร์) ให้กับโมเดลมนุษย์ 3D ได้โดยอัตโนมัติ โดยการผูกเมชเข้ากับมันเพื่อให้พร้อมสำหรับแอนิเมชัน สำหรับการนำแอนิเมชันไปใช้กับตัวละครที่มีการ rigging แล้ว ดูที่ Animation API.

โปรดทราบว่าการ rigging โดยอัตโนมัติในขณะนี้ทำงานได้ดีเฉพาะกับ asset มนุษย์มาตรฐาน (สองขา) ที่มีการกำหนดแขนขาและโครงสร้างร่างกายอย่างชัดเจนในขณะนี้

POST/openapi/v1/rigging

สร้างงาน Rigging

เอนด์พอยต์นี้ช่วยให้คุณสร้างงาน rigging ใหม่สำหรับโมเดล 3D ที่กำหนด เมื่อเสร็จสิ้นสำเร็จ จะให้ตัวละครที่มีการ rig ในรูปแบบมาตรฐานและอาจมีแอนิเมชันการเดิน/วิ่งพื้นฐาน

ปัจจุบัน auto-rigging ไม่เหมาะสำหรับโมเดลต่อไปนี้:

เมชที่ไม่มีเท็กซ์เจอร์
แอสเซทที่ไม่ใช่มนุษย์
แอสเซทมนุษย์ที่มีโครงสร้างแขนขาและร่างกายไม่ชัดเจน

เมื่อใช้ input_task_id โมเดลที่มีมากกว่า 300,000 faces ไม่รองรับการ rigging กรุณาใช้ Remesh API เพื่อลดจำนวน face ก่อนการ rigging

เมื่อใช้ model_url ใบหน้าของตัวละครต้องหันไปทางแกน +Z (ทิศทางไปข้างหน้าแบบมาตรฐานของ glTF) โมเดลที่หันไปทางแกนอื่นจะล้มเหลวในการประเมินท่าทาง

พารามิเตอร์

ต้องการเพียงหนึ่งใน input_task_id หรือ model_url เท่านั้น หากให้ทั้งสอง input_task_id จะมีลำดับความสำคัญ

Name
input_task_id
Type
string
จำเป็น
Description
งานนำเข้าที่ต้องการ rigging ปัจจุบันเรารองรับโมเดลมนุษย์ที่มีเท็กซ์เจอร์

Name
model_url
Type
string
จำเป็น
Description
กรุณาให้โมเดล 3D สำหรับ Meshy เพื่อ rig ผ่าน URL ที่เข้าถึงได้สาธารณะหรือ Data URI ปัจจุบันเรารองรับไฟล์ GLB มนุษย์ที่มีเท็กซ์เจอร์ (.glb format)

Name
height_meters
Type
number
ค่าเริ่มต้น 1.7
Description
ความสูงโดยประมาณของโมเดลตัวละครในเมตร ช่วยในการปรับขนาดและความแม่นยำในการ rigging ต้องเป็นจำนวนบวก
Name
texture_image_url
Type
string
Description
ภาพเท็กซ์เจอร์สีพื้นฐานของโมเดลที่ถูก UV-unwrapped URL ที่เข้าถึงได้สาธารณะหรือ Data URI ปัจจุบันเรารองรับรูปแบบ .png

ผลลัพธ์

คุณสมบัติ result ของการตอบสนองประกอบด้วย id ของงาน rigging ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่เป็นที่ยอมรับ สาเหตุทั่วไป:
- ขาดพารามิเตอร์: ต้องให้ model_url หรือ input_task_id
- รูปแบบโมเดลไม่ถูกต้อง: model_url ชี้ไปที่ไฟล์ที่มีนามสกุลที่ไม่รองรับ (รองรับเฉพาะ .glb)
- URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด model_url
- งานนำเข้าไม่ถูกต้อง: input_task_id ไม่อ้างถึงงาน API ที่ถูกต้อง
- จำนวน face เกิน: โมเดลนำเข้ามีมากกว่า 300,000 faces กรุณาใช้ Remesh API เพื่อลดจำนวน face ก่อนการ rigging
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว กรุณาตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอในการดำเนินการนี้
Name
422 - Unprocessable Entity
Description
การประเมินท่าทางล้มเหลว โมเดลที่ให้มาอาจไม่ใช่ตัวละครมนุษย์ที่ถูกต้อง
Name
429 - Too Many Requests
Description
คุณได้เกินการจำกัดอัตราของคุณ

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

ดึงข้อมูลงาน Rigging

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

พารามิเตอร์

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

ผลลัพธ์

การตอบสนองจะมีวัตถุงาน Rigging ตรวจสอบส่วน วัตถุงาน Rigging สำหรับรายละเอียด

Request

GET

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

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

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

ลบงาน Rigging

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

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

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

ผลลัพธ์

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

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/rigging

รายการงาน Rigging

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

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

Request

GET

/openapi/v1/rigging

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

GET/openapi/v1/rigging/:id/stream

สตรีมงาน Rigging

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน Rigging ที่จะสตรีม

การส่งคืน

ส่งคืนสตรีมของ The Rigging Task Objects เป็น Server-Sent Events

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

วัตถุงาน Rigging

วัตถุงาน Rigging แทนหน่วยงานสำหรับการ rigging ตัวละคร

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน
Name
type
Type
string
Description
ประเภทของงาน Rigging ค่านี้คือ rig
Name
status
Type
string
Description
สถานะของงาน ค่าที่เป็นไปได้: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
ความคืบหน้าของงาน (0-100) 0 ถ้ายังไม่เริ่ม, 100 ถ้าสำเร็จ
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อสร้างงาน
ไทม์สแตมป์แสดงจำนวนมิลลิวินาทีที่ผ่านไปตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 PM GMT แสดงเป็น 1693569600000 ซึ่งใช้กับ ทุก ไทม์สแตมป์ใน Meshy API
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อเริ่มประมวลผลงาน 0 ถ้ายังไม่เริ่ม
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อสิ้นสุดงาน 0 ถ้ายังไม่สิ้นสุด
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ยุค) เมื่อผลลัพธ์ของงานหมดอายุและอาจถูกลบ
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, null ในกรณีอื่น
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดตัวละครที่ rigged ในรูปแบบ FBX
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดตัวละครที่ rigged ในรูปแบบ GLB
- Name
  basic_animations
  Type
  object (optional)
  Description
  ประกอบด้วย URL สำหรับแอนิเมชันเริ่มต้น (เช่น ถ้า generate_basic_animations ถูกตั้งค่าเป็นจริงโดยปริยายหรือเปิดใช้งานโดยค่าเริ่มต้น)
  Name
  walking_glb_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันเดินในรูปแบบ GLB (พร้อมสกิน)
  Name
  walking_fbx_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันเดินในรูปแบบ FBX (พร้อมสกิน)
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดอาร์เมเจอร์แอนิเมชันเดินในรูปแบบ GLB
  Name
  running_glb_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันวิ่งในรูปแบบ GLB (พร้อมสกิน)
  Name
  running_fbx_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดแอนิเมชันวิ่งในรูปแบบ FBX (พร้อมสกิน)
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL สำหรับดาวน์โหลดอาร์เมเจอร์แอนิเมชันวิ่งในรูปแบบ GLB
Name
preceding_tasks
Type
integer
Description
จำนวนงานที่อยู่ก่อนหน้าในคิว มีความหมายเฉพาะเมื่อสถานะคือ PENDING

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}