API การริกกิง

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

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

POST/openapi/v1/rigging

สร้างงาน Rigging

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

ปัจจุบัน 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 ทำ rigging ผ่าน URL ที่เข้าถึงได้แบบสาธารณะหรือ Data URI ขณะนี้เรารองรับไฟล์ GLB ฮิวแมนนอยด์ที่มีเท็กซ์เจอร์ (รูปแบบ .glb)

Name
height_meters
Type
number
ค่าเริ่มต้น 1.7
Description
ความสูงโดยประมาณของโมเดลตัวละครในหน่วยเมตร สิ่งนี้ช่วยเรื่องความแม่นยำในการปรับสเกลและ rigging ต้องเป็นจำนวนบวก
Name
texture_image_url
Type
string
Description
ภาพเท็กซ์เจอร์สีพื้นฐานของโมเดลที่คลี่ UV แล้ว 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/:id/stream

สตรีมงาน Rigging

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

พารามิเตอร์

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

ผลลัพธ์ที่ส่งคืน

ส่งคืนสตรีมของออบเจ็กต์งาน Riggingในรูปแบบ 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
progress ของงาน (0-100) เป็น 0 หากยังไม่เริ่ม และเป็น 100 หากสำเร็จ
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ (มิลลิวินาทีตั้งแต่ epoch) เมื่อสร้างงาน
ไทม์สแตมป์แสดงจำนวนมิลลิวินาทีที่ผ่านไปตั้งแต่วันที่ 1 มกราคม 1970 UTC ตาม มาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 PM 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 มิฉะนั้นจะเป็น null
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL ที่ดาวน์โหลดได้สำหรับตัวละครที่ทำ rigging แล้วในรูปแบบ FBX
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL ที่ดาวน์โหลดได้สำหรับตัวละครที่ทำ rigging แล้วในรูปแบบ GLB
- Name
  basic_animations
  Type
  object (optional)
  Description
  มี URL สำหรับแอนิเมชันเริ่มต้น (เช่น หาก generate_basic_animations เป็น true โดยนัยหรือเปิดใช้งานตามค่าเริ่มต้น)
  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
}