API การพิมพ์หลายสี
แปลงโมเดล 3 มิติเป็นรูปแบบ 3MF หลายสีสำหรับการพิมพ์ 3 มิติ พร้อมจานสีที่กำหนดค่าได้สูงสุด 16 สี
สร้างงานพิมพ์ 3 มิติแบบหลายสี
เอนด์พอยต์นี้สร้างงานพิมพ์ 3 มิติแบบหลายสีใหม่ งานนี้จะแปลงโมเดล 3 มิติให้เป็นไฟล์ 3MF แบบหลายสีที่เหมาะสำหรับการพิมพ์ 3 มิติ
งานนี้จะทำงานในพื้นหลัง สำหรับระยะเวลาที่มักใช้ โปรดดู Processing Times
พารามิเตอร์
ต้องระบุ input_task_id หรือ model_url เพียงอย่างใดอย่างหนึ่งเท่านั้น หากระบุทั้งสองอย่าง input_task_id จะมีลำดับความสำคัญก่อน
- Name
- input_task_id
- Type
- string
- จำเป็น
- Description
ID ของงานที่สำเร็จแล้วเพื่อใช้เป็นข้อมูลนำเข้า ประเภทงานที่รองรับ: Image to 3D, Multi-Image to 3D, Text to 3D, Remesh และ Retexture งานนั้นต้องมีสถานะเป็น
SUCCEEDED
- Name
- model_url
- Type
- string
- จำเป็น
- Description
URL ที่เข้าถึงได้แบบสาธารณะของโมเดล
.glbหรือ.fbxหรือ URL แบบ base64data:ของ GLB (data:model/gltf-binary;base64,...) ไฟล์.fbxต้องส่งเป็น URL แบบhttpหรือhttpsขนาดไฟล์สูงสุด: 400 MB สำหรับ URL แบบ
httpหรือhttps, 100 MB สำหรับ URI แบบdata:ไฟล์ที่มีขนาดเกิน 100 MB สามารถมีจำนวนหน้า (faces) ได้สูงสุด 8,000,000 หน้า โดยนับหน้าเป็นรูปสามเหลี่ยม: สี่เหลี่ยมนับเป็น 2 หน้า และเมชที่ถูกวาดซ้ำมากกว่าหนึ่งครั้งจะนับหนึ่งครั้งต่อสำเนา สำหรับไฟล์ที่เกิน 100 MB ไฟล์ FBX ต้องเป็น binary FBX เวอร์ชัน 7.1 หรือใหม่กว่า และไฟล์ GLB ต้องไม่ใช้การบีบอัดแบบ Draco
- Name
- max_colors
- Type
- integer
- ค่าเริ่มต้น 4
- Description
จำนวนสีสูงสุดในจานสีผลลัพธ์
ช่วงค่าที่ใช้ได้:
1ถึง16
- Name
- style
- Type
- string
- ค่าเริ่มต้น realistic
- Description
รูปแบบสีที่มองเห็นได้ของไฟล์ 3MF ที่สร้างขึ้น
ค่าที่ใช้ได้:
realistic: สุ่มตัวอย่างสีโดยตรงจากเท็กซ์เจอร์ของโมเดลเพื่อให้ได้รายละเอียดที่ละเอียดและสมจริง ไฟล์ที่ได้จะมีขนาดใหญ่กว่าcartoon: ทำให้สีแบนราบเป็นพื้นที่ที่สม่ำเสมอและชัดเจนเพื่อให้ได้ลุคที่มีสไตล์ ไฟล์ที่ได้จะมีขนาดเล็กกว่า
ข้อมูลนำเข้าต้องมีสี:
realisticต้องมีเท็กซ์เจอร์สีพื้นฐานเพียงแบบเดียวพร้อมพิกัด UV บนทุกส่วนของเมช ส่วนcartoonก็ยอมรับสีแบบต่อจุดยอด (per-vertex colors) ได้เช่นกัน โมเดลที่ไม่มีเท็กซ์เจอร์ (สีขาว) จะถูกปฏิเสธ — ดูmodel_missing_texture
- Name
- max_depth
- Type
- integer
- ค่าเริ่มต้น 4
- Description
ระดับความลึกของการแบ่งย่อย (subdivision depth) ที่ใช้ในการสุ่มตัวอย่างสีของเท็กซ์เจอร์ลงบนเมช ค่าที่สูงขึ้นจะจับรายละเอียดสีได้ละเอียดขึ้น แต่แลกมาด้วยไฟล์ที่มีขนาดใหญ่ขึ้น ใช้ได้เฉพาะกับสไตล์
realisticเท่านั้น จะถูกละเว้นสำหรับcartoonช่วงค่าที่ใช้ได้:
3ถึง6
- Name
- printer_brand
- Type
- string
- ค่าเริ่มต้น bambu
- Description
แบรนด์เครื่องพิมพ์ที่ค่าที่ตั้งไว้ล่วงหน้าของสไลเซอร์จะถูกเขียนลงใน 3MF เพื่อให้ไฟล์เปิดในสไลเซอร์ของแบรนด์นั้นพร้อมเครื่องพิมพ์ เส้นไหมพิมพ์ (filament) และโปรไฟล์กระบวนการที่ตรงกัน แต่ละแบรนด์ใช้เครื่องพิมพ์เริ่มต้นที่มีหัวฉีดขนาด 0.4 มม.
ค่าที่ใช้ได้:
bambu,anycubic,creality,elegoo,flashforge,prusa,qidi,snapmaker,ankermake
ผลลัพธ์ที่ได้
พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงานพิมพ์ 3 มิติที่สร้างขึ้นใหม่
รูปแบบความล้มเหลว
- Name
400 - Bad Request- Description
คำขอนี้ไม่สามารถยอมรับได้ สาเหตุทั่วไปได้แก่:
- ขาดพารามิเตอร์: ต้องระบุ
model_urlหรือinput_task_idอย่างใดอย่างหนึ่ง - รูปแบบโมเดลไม่ถูกต้อง:
model_urlชี้ไปยังไฟล์ที่มีนามสกุลที่ไม่รองรับ (รองรับเฉพาะ.glbและ.fbxเท่านั้น) - URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด
model_urlได้ - ไฟล์โมเดลมีขนาดใหญ่เกินไป: ไฟล์
model_urlมีขนาดเกิน 400 MB (URL แบบhttpหรือhttps) หรือ 100 MB (URI แบบdata:) - มีจำนวนหน้ามากเกินไป: ไฟล์
model_urlมีขนาดเกิน 100 MB และมีจำนวนหน้ามากกว่า 8,000,000 หน้า โปรดลดจำนวนหน้า แล้วส่งไฟล์อีกครั้ง - ASCII FBX ขนาดเกิน 100 MB: ไฟล์
model_urlเป็น ASCII FBX ที่มีขนาดเกิน 100 MB โปรดส่งเป็น binary FBX หรือ GLB แทน - ไฟล์โมเดลไม่สามารถอ่านได้: ไฟล์
model_urlมีขนาดเกิน 100 MB และไม่สามารถอ่านส่วนหัวของไฟล์ได้ เช่น GLB ที่บีบอัดด้วย Draco หรือ binary FBX ที่เก่ากว่าเวอร์ชัน 7.1 - ส่วนหัวของโมเดลซับซ้อนเกินไป: ไฟล์
model_urlมีขนาดเกิน 100 MB และส่วนหัวของไฟล์มีเมช โหนด หรือเรคอร์ดมากเกินไปที่จะตรวจสอบได้ โปรดลดจำนวนออบเจ็กต์ในไฟล์ แล้วส่งอีกครั้ง - งานนำเข้าไม่ถูกต้อง:
input_task_idต้องอ้างอิงถึงงานที่สำเร็จแล้ว - max_colors ไม่ถูกต้อง: ค่าต้องอยู่ระหว่าง 1 ถึง 16
- style ไม่ถูกต้อง: ค่าต้องเป็น
realisticหรือcartoon - max_depth ไม่ถูกต้อง: ค่าต้องอยู่ระหว่าง 3 ถึง 6
- printer_brand ไม่ถูกต้อง: ค่าต้องเป็นหนึ่งในแบรนด์ที่ระบุไว้ข้างต้น
- ไม่มีแหล่งที่มาของสี: โมเดลนำเข้าไม่มีเท็กซ์เจอร์สีพื้นฐาน (
realisticต้องการเท็กซ์เจอร์เพียงแบบเดียวพร้อม UV บนทุกส่วนของเมช) และไม่มีสีแบบจุดยอด (cartoonยอมรับได้ทั้งสองแบบ) โปรดใส่เท็กซ์เจอร์ให้โมเดลก่อน หรือใช้cartoonสำหรับโมเดลที่มีสีแบบจุดยอด ไฟล์ที่อัปโหลดแบบ.fbxจะถูกตรวจสอบหลังจากที่งานทำการปรับให้เป็นมาตรฐานแล้ว และจะล้มเหลวด้วยmodel_missing_textureแทน
- ขาดพารามิเตอร์: ต้องระบุ
- Name
401 - Unauthorized- Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
- Name
402 - Payment Required- Description
เครดิตไม่เพียงพอสำหรับการดำเนินงานนี้
- Name
429 - Too Many Requests- Description
คุณใช้งานเกินขีดจำกัดอัตราที่กำหนดไว้แล้ว
Request
# Convert a 3D model to a multi-color 3MF with a Creality slicer preset
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"max_colors": 8,
"printer_brand": "creality"
}'
Response
{
"result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
เรียกดูงานพิมพ์ 3 มิติแบบหลายสี
เอนด์พอยต์นี้ใช้สำหรับเรียกดูงานพิมพ์ 3 มิติแบบหลายสีด้วย ID ของงานนั้น
พารามิเตอร์
- Name
- id
- Type
- path
- Description
ID ของงานพิมพ์ 3 มิติที่ต้องการเรียกดู
ค่าที่ส่งกลับ
อ็อบเจ็กต์ของงานพิมพ์ 3 มิติ
Request
curl https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-multi-color",
"model_urls": {
"3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 10
}
ลบงานพิมพ์ 3D แบบหลายสี
เอนด์พอยต์นี้จะลบงานพิมพ์ 3D แบบหลายสีอย่างถาวร รวมถึงโมเดลและข้อมูลที่เกี่ยวข้องทั้งหมด การกระทำนี้ไม่สามารถย้อนกลับได้
Path Parameters
- Name
- id
- Type
- path
- Description
ID ของงานพิมพ์ 3D แบบหลายสีที่ต้องการลบ
สถานะของงาน
งานที่ยังอยู่ในสถานะ PENDING จะถูกลบ และเครดิตที่ถูกใช้ไปตอนสร้างงานจะได้รับคืน
งานที่อยู่ในสถานะ IN_PROGRESS แล้วไม่สามารถลบได้ คำขอจะถูกปฏิเสธด้วย
409 Conflict และงานจะยังคงทำงานต่อไป เครดิตสำหรับงานที่ worker ได้เริ่มดำเนินการแล้ว
จะไม่สามารถขอคืนได้ ดังนั้นการลบงานขณะกำลังทำงานอยู่จะทำให้คุณเสียทั้งเครดิตและผลลัพธ์
ให้รอจนกว่างานจะถึงสถานะ SUCCEEDED, FAILED หรือ CANCELED แล้วจึงค่อยลบ
งานที่อยู่ในสถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) จะถูกลบโดยไม่มีการคืนเครดิต
ค่าที่ส่งกลับ
ส่งค่ากลับเป็น 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่องานอยู่ในสถานะ
IN_PROGRESS
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-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."
}
List Multi-Color 3D Print Tasks
เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงานพิมพ์ 3D แบบหลายสีได้
พารามิเตอร์
แอตทริบิวต์ที่ไม่บังคับ
- Name
- page_num
- Type
- integer
- Description
หมายเลขหน้าสำหรับการแบ่งหน้า เริ่มต้นและมีค่าเริ่มต้นเป็น
1
- Name
- page_size
- Type
- integer
- Description
จำนวนรายการต่อหน้า ค่าเริ่มต้นคือ
10รายการ สูงสุดที่อนุญาตคือ100รายการ
- Name
- sort_by
- Type
- string
- Description
ฟิลด์ที่ใช้สำหรับเรียงลำดับ ค่าที่สามารถใช้ได้มีดังนี้:
+created_at: เรียงลำดับตามเวลาที่สร้างจากน้อยไปมาก-created_at: เรียงลำดับตามเวลาที่สร้างจากมากไปน้อย
ผลลัพธ์ที่ได้
คืนค่าเป็นรายการแบบแบ่งหน้าของ The 3D Print Task Objects
Request
curl https://api.meshy.ai/openapi/v1/print/multi-color?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-multi-color",
"model_urls": {
"3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 10
}
]
สตรีมงานพิมพ์ 3D หลายสี
เอนด์พอยต์นี้สตรีมการอัปเดตแบบเรียลไทม์สำหรับงานพิมพ์ 3D หลายสี โดยใช้ Server-Sent Events (SSE)
พารามิเตอร์
- Name
- id
- Type
- path
- Description
ตัวระบุเฉพาะสำหรับงานพิมพ์ 3D หลายสีที่ต้องการสตรีม
ค่าที่ส่งกลับ
ส่งกลับสตรีมของ The 3D Print Task Objects ในรูปแบบ Server-Sent Events
สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะมีเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น
Request
curl -N https://api.meshy.ai/openapi/v1/print/multi-color/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
"id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
"type": "print-multi-color",
"model_urls": {
"3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
},
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 10
}
The 3D Print Task Object
- Name
- id
- Type
- string
- Description
ตัวระบุเฉพาะสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID สำหรับ id ของงานเป็นรายละเอียดการใช้งาน แต่คุณ ไม่ควร ตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
- Name
- type
- Type
- string
- Description
ประเภทของงาน 3D Print ค่านี้คือ
print-multi-color
- Name
- model_urls
- Type
- object
- Description
URL สำหรับดาวน์โหลดไฟล์โมเดล 3D ที่สร้างโดย Meshy พร็อพเพอร์ตี้สำหรับฟอร์แมตนั้นจะถูกละไว้หากฟอร์แมตนั้นไม่ได้ถูกสร้างขึ้น แทนที่จะคืนค่าเป็นสตริงว่าง
- Name
3mf- Type
- string
- Description
URL สำหรับดาวน์โหลดไฟล์ 3MF แบบหลายสี
- Name
- progress
- Type
- integer
- Description
ความคืบหน้าของงาน หากงานยังไม่เริ่มต้น พร็อพเพอร์ตี้นี้จะเป็น
0เมื่องานสำเร็จแล้ว ค่านี้จะกลายเป็น100
- Name
- status
- Type
- string
- Description
สถานะของงาน ค่าที่เป็นไปได้คือค่าใดค่าหนึ่งจาก
PENDING,IN_PROGRESS,SUCCEEDED,FAILED
- 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
จำนวนเครดิตที่ใช้ไปสำหรับงานนี้ จะปรากฏเมื่อสถานะของงานเป็น
PENDING,IN_PROGRESS, หรือSUCCEEDEDจะคืนค่า0สำหรับงานที่FAILED(เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)
The 3D Print Task Object
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-multi-color",
"model_urls": {
"3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 10
}