Rigging API

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

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

POST/openapi/v1/rigging

สร้างงานริกกิ้ง

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

งานนี้ทำงานในเบื้องหลัง สำหรับระยะเวลาที่ใช้โดยทั่วไป ดูได้ที่ Processing Times

ปัจจุบัน ระบบริกอัตโนมัติยังไม่เหมาะกับโมเดลต่อไปนี้:

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

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

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

พารามิเตอร์

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

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

Name
model_url
Type
string
จำเป็น
Description
กรุณาระบุโมเดล 3D ให้ Meshy ทำการริกผ่าน URL ที่เข้าถึงได้แบบสาธารณะหรือ Data URI ปัจจุบันเรารองรับไฟล์ GLB รูปร่างคล้ายมนุษย์ที่มีเท็กซ์เจอร์ (รูปแบบ .glb)
ขนาดไฟล์สูงสุด: 400 MB สำหรับ URL แบบ http หรือ https, 100 MB สำหรับ URI แบบ data:
ไฟล์ที่มีขนาดเกิน 100 MB และมีมากกว่า 10,000,000 หน้า จะส่งคืน 400 โดยหน้าจะถูกนับเป็นสามเหลี่ยม และเมชที่ถูกวาดซ้ำมากกว่าหนึ่งครั้งจะถูกนับหนึ่งครั้งต่อสำเนา ไฟล์ GLB ที่มีขนาดเกิน 100 MB ต้องไม่ใช้การบีบอัดแบบ Draco

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

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

พร็อพเพอร์ตี้ result ของการตอบกลับประกอบด้วย id ของงานที่สร้างขึ้นใหม่สำหรับการริก

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถยอมรับได้ สาเหตุทั่วไปได้แก่:
- ขาดพารามิเตอร์: ต้องระบุ model_url หรือ input_task_id อย่างใดอย่างหนึ่ง
- รูปแบบโมเดลไม่ถูกต้อง: model_url ชี้ไปยังไฟล์ที่มีนามสกุลที่ไม่รองรับ (รองรับเฉพาะ .glb)
- ไม่สามารถเข้าถึง URL ได้: ไม่สามารถดาวน์โหลด model_url ได้
- ไฟล์โมเดลมีขนาดใหญ่เกินไป: ไฟล์ model_url มีขนาดเกิน 400 MB (URL แบบ http หรือ https) หรือ 100 MB (URI แบบ data:)
- มีจำนวนหน้ามากเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และมีมากกว่า 10,000,000 หน้า โปรดลดจำนวนหน้า แล้วส่งไฟล์อีกครั้ง
- ไม่สามารถอ่านไฟล์โมเดลได้: ไฟล์ model_url มีขนาดเกิน 100 MB และไม่สามารถอ่านส่วนหัวได้ เช่น ไฟล์ GLB ที่บีบอัดด้วย Draco
- ส่วนหัวของโมเดลซับซ้อนเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และส่วนหัวมีเมช โหนด หรือเรคคอร์ดมากเกินกว่าจะตรวจสอบได้ โปรดลดจำนวนออบเจ็กต์ในไฟล์ แล้วส่งอีกครั้ง
- ภาพมีขนาดใหญ่เกินไป: ภาพ texture_image_url มีขนาดเกิน 20 MB
- งานนำเข้าไม่ถูกต้อง: input_task_id ไม่ได้อ้างอิงถึงงาน API ที่ถูกต้อง
- จำนวนหน้าเกินกำหนด: โมเดลที่นำเข้ามีมากกว่า 300,000 หน้า กรุณาใช้ Remesh API เพื่อลดจำนวนหน้าก่อนทำการริก
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 ของงานที่ถูกต้อง โปรดดู The Rigging Task Object เพื่อดูว่ามีพร็อพเพอร์ตี้ใดบ้างที่รวมอยู่

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะ (Unique identifier) สำหรับงาน rigging ที่ต้องการเรียกดู

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

การตอบกลับประกอบด้วยอ็อบเจกต์ Rigging Task ดูรายละเอียดได้ที่ส่วน The Rigging Task Object

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 ของเว็บแอป ใช้เอนด์พอยต์นี้เพื่อค้นหางานที่คุณไม่มี 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
}

The Rigging Task Object

Rigging Task Object แสดงถึงหน่วยงานสำหรับการ rigging ตัวละคร

Properties

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
ไทม์สแตมป์ (มิลลิวินาทีนับจาก 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) เมื่อ asset ผลลัพธ์ของงานหมดอายุและอาจถูกลบ
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 ของ asset ผลลัพธ์หากงาน 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 ถูกตั้งเป็นจริงโดยนัยหรือเปิดใช้งานโดยค่าเริ่มต้น)
  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
}