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 อย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดที่เกี่ยวข้อง การกระทำนี้ไม่สามารถย้อนกลับได้

Path Parameters

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

สถานะของงาน

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

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

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

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

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

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

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

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
}