Multi-Color Print API
แปลงโมเดล 3 มิติเป็นไฟล์รูปแบบ 3MF หลายสีสำหรับการพิมพ์ 3 มิติ พร้อมจานสีที่สามารถกำหนดค่าได้สูงสุด 16 สี
สร้างงานพิมพ์ 3 มิติหลายสี
เอนด์พอยต์นี้สร้างงานพิมพ์ 3 มิติหลายสีใหม่ งานนี้จะแปลงโมเดล 3 มิติเป็นไฟล์ 3MF หลายสีที่เหมาะสำหรับการพิมพ์ 3 มิติ
พารามิเตอร์
ต้องระบุอย่างใดอย่างหนึ่งระหว่าง input_task_id หรือ model_url เท่านั้น หากระบุทั้งสองอย่าง input_task_id จะมีความสำคัญกว่า
- Name
- input_task_id
- Type
- string
- จำเป็น
- Description
ID ของงานที่สำเร็จแล้วซึ่งจะใช้เป็นข้อมูลนำเข้า ประเภทงานที่รองรับ: รูปภาพเป็น 3D, หลายรูปเป็น 3D, ข้อความเป็น 3D, รีเมช และ รีเท็กซ์เจอร์ งานนั้นต้องมีสถานะเป็น
SUCCEEDED
- Name
- model_url
- Type
- string
- จำเป็น
- Description
URL ที่เข้าถึงได้แบบสาธารณะ หรือ Data URI ของโมเดล 3 มิติ ขณะนี้เรารองรับรูปแบบ
.glbและ.fbx
- 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
ผลลัพธ์ที่ได้
พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงานพิมพ์ 3 มิติที่สร้างขึ้นใหม่
รูปแบบความล้มเหลว
- Name
400 - Bad Request- Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- ขาดพารามิเตอร์: ต้องระบุ
model_urlหรือinput_task_idอย่างใดอย่างหนึ่ง - รูปแบบโมเดลไม่ถูกต้อง:
model_urlชี้ไปยังไฟล์ที่มีนามสกุลไม่รองรับ (รองรับเฉพาะ.glbและ.fbx) - URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด
model_urlได้ - งานนำเข้าไม่ถูกต้อง:
input_task_idต้องอ้างอิงถึงงานที่สำเร็จแล้ว - max_colors ไม่ถูกต้อง: ค่าต้องอยู่ระหว่าง 1 ถึง 16
- style ไม่ถูกต้อง: ค่าต้องเป็น
realisticหรือcartoon - ไม่มีแหล่งข้อมูลสี: โมเดลนำเข้าไม่มีเท็กซ์เจอร์สีพื้นฐาน (
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 multi-color 3MF for printing
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
}'
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 และงานจะยังคงทำงานต่อไป เครดิตสำหรับงานที่เวิร์กเกอร์ได้เริ่มดำเนินการไปแล้วจะไม่สามารถขอคืนได้ ดังนั้นการลบงานขณะที่กำลังทำงานอยู่จะทำให้คุณเสียทั้งเครดิตและผลลัพธ์ รอจนกว่างานจะถึงสถานะ
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."
}
แสดงรายการงานพิมพ์ 3D แบบหลายสี
เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงานพิมพ์ 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
ตัวระบุที่ไม่ซ้ำกันสำหรับ task โดยเราใช้ k-sortable UUID สำหรับ task id เป็นรายละเอียดการใช้งานภายใน คุณไม่ควรตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
- Name
- type
- Type
- string
- Description
ประเภทของ task การพิมพ์ 3D ค่าคือ
print-multi-color
- Name
- model_urls
- Type
- object
- Description
URL สำหรับดาวน์โหลดไฟล์โมเดล 3D ที่สร้างโดย Meshy พร็อพเพอร์ตี้สำหรับฟอร์แมตหนึ่ง ๆ จะถูกละเว้นหากไม่ได้สร้างฟอร์แมตนั้นขึ้นมา แทนที่จะส่งกลับเป็นสตริงว่าง
- Name
3mf- Type
- string
- Description
URL สำหรับดาวน์โหลดไฟล์ 3MF แบบหลายสี
- Name
- progress
- Type
- integer
- Description
progress ของ task หากยังไม่เริ่ม task พร็อพเพอร์ตี้นี้จะเป็น
0เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น100
- Name
- status
- Type
- string
- Description
สถานะของ task ค่าที่เป็นไปได้คือหนึ่งใน
PENDING,IN_PROGRESS,SUCCEEDED,FAILED
- Name
- preceding_tasks
- Type
- integer
- Description
จำนวนของ task ที่อยู่ก่อนหน้า
ค่าของฟิลด์นี้มีความหมายก็ต่อเมื่อสถานะของ task เป็น
PENDING
- Name
- created_at
- Type
- timestamp
- Description
ไทม์สแตมป์ของเวลาที่สร้าง task หน่วยเป็นมิลลิวินาที
- Name
- started_at
- Type
- timestamp
- Description
ไทม์สแตมป์ของเวลาที่เริ่ม task หน่วยเป็นมิลลิวินาที หากยังไม่เริ่ม task พร็อพเพอร์ตี้นี้จะเป็น
0
- Name
- finished_at
- Type
- timestamp
- Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาที หาก task ยังไม่เสร็จสิ้น พร็อพเพอร์ตี้นี้จะเป็น
0
- Name
- task_error
- Type
- object
- Description
รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงฉบับเต็มของอ็อบเจ็กต์
task_error
- Name
- consumed_credits
- Type
- integer
- Description
จำนวนเครดิตที่ใช้ไปโดย task นี้ มีค่าเมื่อสถานะของ task เป็น
PENDING,IN_PROGRESS, หรือSUCCEEDEDจะคืนค่า0สำหรับ task ที่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
}