Auto Split API
แบ่งโมเดล 3D ออกเป็นชิ้นส่วนที่พิมพ์แยกกันได้ — โดยอัตโนมัติ ตามชิ้นส่วนที่คุณตั้งชื่อ หรือตามพื้นที่สี — พร้อมตัวเชื่อมต่อที่เป็นตัวเลือก บริเวณที่บางซึ่งเกิดจากการตัดจะได้รับการเสริมความแข็งแรงเสมอ เพื่อให้ทุกชิ้นส่วนพิมพ์ออกมาแบบทึบ
ปัจจุบัน Auto Split รองรับเฉพาะโมเดลที่ ไม่มีพื้นผิว เท่านั้น สำหรับ รูปภาพเป็น 3D และ หลายรูปเป็น 3D ให้สร้างอินพุตโดยตั้งค่า should_texture เป็น false อินพุตที่มีพื้นผิวจะถูกปฏิเสธด้วยรหัส 400
Create an Auto Split Task
เอนด์พอยต์นี้สร้างงาน Auto Split ใหม่ งานนี้จะตัดโมเดลจากงานก่อนหน้าออกเป็นชิ้นส่วนที่พิมพ์แยกกันได้ และคืนค่าโมเดลที่ถูกแบ่งส่วนแล้ว โดยแต่ละชิ้นส่วนจะเป็นออบเจ็กต์ของตัวเองในไฟล์
พารามิเตอร์
- Name
- input_task_id
- Type
- string
- จำเป็น
- Description
ID ของงานที่สำเร็จแล้วซึ่งต้องการแยกโมเดล ประเภทงานที่รองรับ: รูปภาพเป็น 3D, หลายรูปเป็น 3D, ข้อความเป็น 3D (ตัวอย่าง), รีเมช, แปลง และ ปรับขนาด งานนั้นต้องมีสถานะเป็น
SUCCEEDEDและโมเดลของมันต้องถูกสร้างขึ้นด้วย Meshy 6 หรือ Meshy 7 (ai_modelเป็นmeshy-6,meshy-7, หรือlatest) โมเดลแบบโลว์โพลีและ Smart Topology (meshy-t2) ไม่รองรับ
- Name
- mode
- Type
- string
- ค่าเริ่มต้น auto
- Description
วิธีการแบ่งโมเดลออกเป็นส่วนต่างๆ
ค่าที่ใช้ได้:
auto: Meshy เป็นผู้เลือกจุดตัดเองpromptจะถูกละเว้นby_parts: ตัดตามส่วนโครงสร้างที่คุณระบุในpromptเช่น หัว แขน และลำตัวby_color: ตัดตามบริเวณสีที่คุณระบุในpromptต้องใช้อินพุตที่สร้างจากภาพที่อัปโหลด (รูปภาพเป็น 3D หรือ หลายรูปเป็น 3D) อินพุตอื่นๆ จะถูกปฏิเสธด้วย400
mode = by_parts or by_color- Name
- prompt
- Type
- string
- จำเป็น
- Description
อธิบายส่วนที่ต้องการแยก โดยใช้ภาษาใดก็ได้ Meshy จะอ่านชื่อส่วนต่างๆ ได้ 1 ถึง 10 ชื่อจากข้อความนี้ ดังนั้นให้ระบุชื่อชิ้นส่วนแทนการอธิบายโมเดล — ตัวอย่างเช่น
split into the figure and the baseหรือhead, torso, left arm, right arm, legsได้สูงสุด 600 ตัวอักษร มีรูปแบบความล้มเหลว 2 แบบ: คำอธิบายที่อ่านได้ว่าเป็นการแยกส่วนแต่ระบุชื่อส่วนน้อยกว่าสองส่วน (เช่นsplit into individual parts) จะถูกปฏิเสธด้วย400และไม่มีการคิดค่าใช้จ่ายใดๆ ส่วนคำอธิบายที่ Meshy ไม่สามารถอ่านได้เลยจะย้อนกลับไปใช้autoงานยังคงทำงานและถูกคิดค่าใช้จ่ายตามปกติ และการตอบกลับจะมีprompt_ignored: true
- Name
- target_formats
- Type
- array
- ค่าเริ่มต้น ["glb"]
- Description
รูปแบบไฟล์ที่จะส่งออกโมเดลที่แยกส่วนแล้ว แต่ละส่วนจะเป็นออบเจ็กต์แยกต่างหากในทุกรูปแบบไฟล์
glbจะถูกสร้างและคืนค่าในmodel_urlsเสมอ ให้ระบุรูปแบบไฟล์อื่นๆ ที่ต้องการเพิ่มเติมค่าที่ใช้ได้:
glb,obj,fbx,usdz,blend,3mf
- Name
- layout
- Type
- string
- ค่าเริ่มต้น assembled
- Description
วิธีจัดเรียงชิ้นส่วนต่างๆ ในทุกรูปแบบไฟล์ที่ส่งออก และในภาพย่อ
ค่าที่ใช้ได้:
assembled: ชิ้นส่วนคงตำแหน่งเดิมตามโมเดลต้นฉบับon_plate: ชิ้นส่วนถูกวางเรียงแบนราบและกระจายออกบนแท่นพิมพ์ พร้อมสำหรับการสไลซ์ — การจัดเรียงแบบเดียวกับมุมมอง On Plate ในเว็บแอป
ในทั้งสองรูปแบบการจัดเรียง ไฟล์ที่ส่งออกจะมีหนึ่งออบเจ็กต์ต่อหนึ่งชิ้นส่วนเท่านั้น: เศษชิ้นที่ยุบตัวหรือมีลักษณะเป็นจุดที่หลงเหลือจากการตัดจะถูกลบออกก่อนการส่งออก ดังนั้นทุกออบเจ็กต์ที่พบในไฟล์จึงพิมพ์ได้จริง
- Name
- connectors
- Type
- boolean
- ค่าเริ่มต้น false
- Description
เพิ่มตัวเชื่อมแบบเดือยและร่อง (mortise-and-tenon) ที่จุดตัดแต่ละจุด เพื่อให้ชิ้นส่วนที่พิมพ์ออกมาสามารถประกอบเข้าด้วยกันได้
connectors = true- Name
- connector_type
- Type
- string
- ค่าเริ่มต้น cube
- Description
รูปทรงของตัวเชื่อมที่พื้นผิวจุดตัดแต่ละจุด
ค่าที่ใช้ได้:
cube,cylinder
- Name
- connector_size
- Type
- number
- ค่าเริ่มต้น 0.5
- Description
ขนาดของตัวเชื่อมเทียบกับพื้นผิวจุดตัด
ช่วงค่าที่ใช้ได้:
0.1ถึง0.8
- Name
- connector_height
- Type
- number
- ค่าเริ่มต้น 0.1
- Description
ระยะที่ตัวเชื่อมยื่นออกจากพื้นผิวจุดตัด เทียบกับพื้นผิวจุดตัด
ช่วงค่าที่ใช้ได้:
0.1ถึง0.8
ค่าที่ส่งกลับ
พร็อพเพอร์ตี้ result ของการตอบกลับมี id ของงาน Auto Split ที่สร้างขึ้นใหม่
รูปแบบความล้มเหลว
- Name
400 - Bad Request- Description
คำขอนี้ไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- ไม่มี prompt: ต้องระบุ
promptเมื่อmodeเป็นby_partsหรือby_color - prompt ระบุชื่อส่วนน้อยกว่าสองส่วน:
by_parts/by_colorต้องมีอย่างน้อยสองชิ้นส่วนที่ระบุชื่อ (เช่นhead, torso, base) คำสั่งทั่วไปเช่นsplit into individual partsจะถูกปฏิเสธ ไม่มีการคิดค่าใช้จ่ายใดๆ - งานอินพุตไม่รองรับ:
input_task_idต้องอ้างอิงถึงงานที่สำเร็จแล้วในประเภทที่รองรับ ซึ่งสร้างขึ้นด้วย Meshy 6 หรือ Meshy 7 - อินพุตมีพื้นผิว (texture): โมเดลอินพุตมี texture ในขณะนี้รองรับเฉพาะโมเดลที่ไม่มี texture เท่านั้น
- ไม่มีภาพอ้างอิง:
by_colorต้องใช้อินพุตที่สร้างจากภาพที่อัปโหลด - รูปแบบไฟล์ไม่รองรับ:
target_formatsมีstlรวมอยู่ด้วย - ตัวเชื่อมมีค่าอยู่นอกช่วง:
connector_sizeหรือconnector_heightอยู่นอกช่วง0.1ถึง0.8
- ไม่มี prompt: ต้องระบุ
- Name
401 - Unauthorized- Description
การยืนยันตัวตนล้มเหลว กรุณาตรวจสอบ API คีย์ของคุณ
- Name
402 - Payment Required- Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้
- Name
404 - Not Found- Description
input_task_idไม่มีอยู่จริงหรือไม่ได้เป็นของบัญชีของคุณ
- Name
429 - Too Many Requests- Description
คุณได้เกินขีดจำกัดการจำกัดอัตราของคุณแล้ว คำขอ
by_partsและby_colorยังใช้ขีดจำกัดการแยกวิเคราะห์ prompt ร่วมกันที่ 12 คำขอต่อนาทีต่อบัญชี
- Name
503 - Service Unavailable- Description
การแยกส่วนแบบใช้ prompt (
by_partsและby_color) ไม่พร้อมให้บริการชั่วคราว กรุณาลองใหม่ในภายหลัง หรือใช้mode: "auto"ซึ่งไม่ได้รับผลกระทบ ไม่มีการคิดค่าใช้จ่ายใดๆ
Request
# Simple request: let Meshy choose the cuts
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
}'
# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"mode": "by_parts",
"prompt": "split into the figure and the base",
"target_formats": ["glb", "obj"],
"layout": "on_plate",
"connectors": true,
"connector_type": "cylinder",
"connector_size": 0.4
}'
Response
{
"result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
เรียกดูงาน Auto Split
เอนด์พอยต์นี้ใช้เรียกดูงาน Auto Split ตาม ID ของงาน
พารามิเตอร์
- Name
- id
- Type
- path
- Description
ID ของงาน Auto Split ที่ต้องการเรียกดู
ค่าที่ส่งกลับ
ออบเจ็กต์งาน Auto Split
Request
curl https://api.meshy.cn/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-split",
"model_urls": {
"glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
"obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
},
"thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"part_count": 4,
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000082000,
"task_error": null,
"consumed_credits": 10
}
ลบงาน Auto Split
เอนด์พอยต์นี้ใช้สำหรับลบงาน Auto Split อย่างถาวร รวมถึงโมเดลและข้อมูลทั้งหมดที่เกี่ยวข้อง การดำเนินการนี้ไม่สามารถย้อนกลับได้
Path Parameters
- Name
- id
- Type
- path
- Description
ID ของงาน Auto Split ที่ต้องการลบ
สิ่งที่ได้รับกลับมา
ส่งคืน 200 OK เมื่อสำเร็จ
Request
curl --request DELETE \
--url https://api.meshy.cn/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// Returns 200 Ok on success.
List Auto Split Tasks
เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงาน Auto Split ได้
พารามิเตอร์
แอตทริบิวต์ที่ไม่บังคับ
- Name
- page_num
- Type
- integer
- Description
หมายเลขหน้าสำหรับการแบ่งหน้า เริ่มต้นและมีค่าเริ่มต้นเป็น
1
- Name
- page_size
- Type
- integer
- Description
จำนวนรายการสูงสุดต่อหน้า ค่าเริ่มต้นคือ
10รายการ ค่าสูงสุดที่อนุญาตคือ100รายการ หากระบุค่ามากกว่านี้จะถูกจำกัดไว้ที่100
- Name
- sort_by
- Type
- string
- Description
ฟิลด์ที่ใช้ในการเรียงลำดับ ค่าที่ใช้ได้:
+created_at: เรียงลำดับตามเวลาที่สร้างจากน้อยไปมาก-created_at: เรียงลำดับตามเวลาที่สร้างจากมากไปน้อย
ค่าที่ส่งกลับ
ส่งคืนรายการแบบแบ่งหน้าของ The Auto Split Task Objects
Request
curl https://api.meshy.cn/openapi/v1/print/split?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-split",
"model_urls": {
"glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"part_count": 4,
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000082000,
"task_error": null,
"consumed_credits": 10
}
]
สตรีมงาน Auto Split
เอนด์พอยต์นี้จะสตรีมข้อมูลอัปเดตแบบเรียลไทม์สำหรับงาน Auto Split โดยใช้ Server-Sent Events (SSE)
พารามิเตอร์
- Name
- id
- Type
- path
- Description
ตัวระบุเฉพาะสำหรับงาน Auto Split ที่ต้องการสตรีม
สิ่งที่ได้รับกลับมา
ส่งคืนสตรีมของ The Auto Split Task Objects ในรูปแบบ Server-Sent Events
ทุกอีเวนต์ message จะมีอ็อบเจกต์งานฉบับเต็มตามที่ส่งคืนโดย Retrieve an Auto Split Task รวมถึง consumed_credits, ไทม์สแตมป์ต่างๆ และ prompt_ignored; ในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ที่เปลี่ยนแปลงระหว่างแต่ละเฟรมคือ progress, status, started_at และ preceding_tasks ส่วน model_urls, thumbnail_url, part_count และ parts จะปรากฏขึ้นเมื่อสถานะถึง SUCCEEDED แล้ว อีเวนต์ error จะมีเพียง status_code และ message เท่านั้น ดังนั้นควรแยกกรณีตามชื่ออีเวนต์ก่อนที่จะอ่านค่า status
Request
curl -N https://api.meshy.cn/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
"id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
"type": "print-split",
"model_urls": {
"glb": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
"part_count": 4,
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000082000,
"task_error": null,
"consumed_credits": 10
}
The Auto Split Task Object
งาน Auto Split จะมีเพียงคุณสมบัติด้านล่างนี้เท่านั้น ฟิลด์ prompt สำหรับการสร้างที่ออบเจ็กต์งานอื่น ๆ มี (name, object_prompt, texture_prompt และอื่น ๆ), model_url เดี่ยว, และ texture_urls จะไม่ถูกกำหนดค่าสำหรับการแยกและจะไม่ถูกส่งกลับมา คุณสมบัติที่จะถูกเติมค่าขณะที่งานกำลังดำเนินการ (thumbnail_url, model_urls, ไทม์สแตมป์ต่าง ๆ) จะปรากฏอยู่เสมอ โดยจะว่างเปล่าจนกว่าจะมีค่า ดังนั้นชุดของคีย์จะไม่เปลี่ยนแปลงระหว่าง PENDING และ SUCCEEDED
- Name
- id
- Type
- string
- Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID สำหรับ id ของงานเป็นรายละเอียดการดำเนินการ แต่คุณไม่ควรตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
- Name
- type
- Type
- string
- Description
ประเภทของงาน ค่าคือ
print-split
- Name
- model_urls
- Type
- object
- Description
URL ที่ดาวน์โหลดได้สำหรับโมเดลที่ถูกแยก โดยมีหนึ่ง URL ต่อหนึ่งรูปแบบที่ร้องขอ แต่ละชิ้นส่วนเป็นออบเจ็กต์แยกต่างหากในไฟล์ คุณสมบัติสำหรับรูปแบบใดรูปแบบหนึ่งจะถูกละไว้หากไม่ได้ร้องขอรูปแบบนั้น
- Name
glb- Type
- string
- Description
URL ที่ดาวน์โหลดได้สำหรับโมเดลที่ถูกแยกในรูปแบบ GLB
- Name
obj- Type
- string
- Description
URL ที่ดาวน์โหลดได้สำหรับโมเดลที่ถูกแยกในรูปแบบ OBJ
- Name
fbx- Type
- string
- Description
URL ที่ดาวน์โหลดได้สำหรับโมเดลที่ถูกแยกในรูปแบบ FBX
- Name
usdz- Type
- string
- Description
URL ที่ดาวน์โหลดได้สำหรับโมเดลที่ถูกแยกในรูปแบบ USDZ
- Name
blend- Type
- string
- Description
URL ที่ดาวน์โหลดได้สำหรับโมเดลที่ถูกแยกในรูปแบบ Blender
- Name
3mf- Type
- string
- Description
URL ที่ดาวน์โหลดได้สำหรับโมเดลที่ถูกแยกในรูปแบบ 3MF
- Name
- thumbnail_url
- Type
- string
- Description
URL ที่ดาวน์โหลดได้สำหรับภาพตัวอย่างที่แสดงผลของโมเดลที่ถูกแยก โดยแต่ละชิ้นส่วนจะมีสีที่แตกต่างกัน ในรูปแบบ
layoutที่ร้องขอ
- Name
- prompt_ignored
- Type
- boolean
- Description
เป็น
trueเมื่อpromptของคำขอby_partsหรือby_colorไม่ได้ระบุชื่อชิ้นส่วนใด ๆ ดังนั้น Meshy จึงแยกโมเดลโดยอัตโนมัติแทน — ชื่อชิ้นส่วนในผลลัพธ์เป็นของ Meshy ไม่ใช่ของคุณ ปรากฏตั้งแต่PENDINGเป็นต้นไป จะถูกละไว้สำหรับงานautoและเมื่อใดก็ตามที่ prompt ถูกปฏิบัติตาม
- Name
- part_count
- Type
- integer
- Description
จำนวนชิ้นส่วนที่สามารถพิมพ์ได้ในโมเดลที่ถูกแยก — หนึ่งชิ้นต่อหนึ่งออบเจ็กต์ในไฟล์ที่ส่งออก ชิ้นส่วนบาง ๆ ที่ยุบตัวซึ่งการแบ่งส่วนไม่สามารถแปลงให้เป็นชิ้นงานที่พิมพ์ได้จะถูกลบออกจากไฟล์ก่อนการส่งออก และจะไม่ถูกนับรวม
- Name
- progress
- Type
- integer
- Description
progress ของงาน หากงานยังไม่เริ่มดำเนินการ คุณสมบัตินี้จะเป็น
0เมื่องานสำเร็จแล้ว ค่านี้จะกลายเป็น100
- Name
- status
- Type
- string
- Description
สถานะของงาน ค่าที่เป็นไปได้คือค่าใดค่าหนึ่งจาก
PENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED
- Name
- preceding_tasks
- Type
- integer
- Description
จำนวนงานที่อยู่ก่อนหน้า
ค่าของฟิลด์นี้มีความหมายก็ต่อเมื่อสถานะของงานเป็น
PENDINGเท่านั้น
- Name
- created_at
- Type
- timestamp
- Description
ไทม์สแตมป์ของเวลาที่งานถูกสร้างขึ้น หน่วยเป็นมิลลิวินาที
- Name
- started_at
- Type
- timestamp
- Description
ไทม์สแตมป์ของเวลาที่งานเริ่มดำเนินการ หน่วยเป็นมิลลิวินาที หากงานยังไม่เริ่มดำเนินการ คุณสมบัตินี้จะเป็น
0
- Name
- finished_at
- Type
- timestamp
- Description
ไทม์สแตมป์ของเวลาที่งานเสร็จสิ้น หน่วยเป็นมิลลิวินาที หากงานยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น
0
- Name
- task_error
- Type
- object
- Description
รายละเอียดข้อผิดพลาดสำหรับงานที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงออบเจ็กต์
task_errorฉบับเต็ม
- Name
- consumed_credits
- Type
- integer
- Description
จำนวนเครดิตที่ถูกใช้ไปสำหรับงานนี้ จะปรากฏอยู่เสมอ: เป็น
10เมื่องานได้รับการยอมรับแล้ว และเป็น0สำหรับงานที่FAILEDเนื่องจากค่าใช้จ่ายจะถูกคืนเมื่อล้มเหลว การลบงานขณะที่ยังอยู่ในสถานะPENDINGก็จะได้รับการคืนเครดิตเช่นกัน
The Auto Split Task Object
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-split",
"model_urls": {
"glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
"obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
},
"thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
"part_count": 4,
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000082000,
"task_error": null,
"consumed_credits": 10
}