Multi-Color Print API

แปลงโมเดล 3 มิติให้เป็นไฟล์ 3MF หลายสีสำหรับการพิมพ์ 3 มิติ เลือกชุดสีได้สูงสุด 16 สี และพรีเซ็ตของสไลเซอร์สำหรับแบรนด์เครื่องพิมพ์ของคุณ

POST/openapi/v1/print/multi-color

สร้างงาน Multi-Color Print

สร้างงาน Multi-Color Print ซึ่งแปลงโมเดล 3 มิติให้เป็นไฟล์ 3MF หลายสีสำหรับการพิมพ์ 3 มิติ งานนี้ทำงานในพื้นหลัง ดูระยะเวลาที่งานมักใช้ได้ที่ ระยะเวลาการประมวลผล

Request

POST

/openapi/v1/print/multi-color

# 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"
}

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
ต้องระบุ เว้นแต่คุณจะส่ง model_url คือ ID ของงานที่มีโมเดลที่คุณต้องการพิมพ์ เช่น งาน รูปภาพเป็น 3D, หลายรูปเป็น 3D, ข้อความเป็น 3D, รีเมช หรือ รีเท็กซ์เจอร์ งานนี้ต้องเป็นงานที่คุณสร้างด้วย API และมีสถานะเป็น SUCCEEDED
Multi-Color Print จะอ่านไฟล์ GLB ของงาน ซึ่งสามารถมีหน้า (faces) ได้สูงสุด 8,000,000 หน้า โมเดลที่มีหน้ามากกว่านี้จะคืนค่า 400 ในกรณีนี้ ให้รันงาน รีเมช กับโมเดลก่อน แล้วส่ง ID ของงานรีเมชแทน

Name
model_url
Type
string
จำเป็น
Description
ต้องระบุ เว้นแต่คุณจะส่ง input_task_id คือโมเดลที่จะพิมพ์ ในรูปแบบ URL สาธารณะหรือ Data URI หากคุณส่งทั้งสองอย่าง Meshy จะใช้ input_task_id
URL แบบ http หรือ https ต้องชี้ไปยังไฟล์ .glb หรือ .fbx ที่มีขนาดไม่เกิน 400 MB ส่วน Data URI ต้องเก็บไฟล์ GLB แบบ base64 ที่มีขนาดไม่เกิน 100 MB โดยใช้ data:model/gltf-binary;base64, สำหรับไฟล์ .fbx ให้ส่งเป็น URL แบบ http หรือ https
ไฟล์ที่มีขนาดเกิน 100 MB ต้องเป็นไปตามกฎเหล่านี้ด้วย:
- มีหน้า (faces) ได้สูงสุด 8,000,000 หน้า Meshy นับหน้าเป็นสามเหลี่ยม ดังนั้นรูปสี่เหลี่ยมจะนับเป็น 2 และเมชที่วาดซ้ำมากกว่าหนึ่งครั้งจะนับหนึ่งครั้งต่อสำเนา
- ไฟล์ FBX ต้องเป็น binary FBX เวอร์ชัน 7.1 หรือใหม่กว่า
- ไฟล์ GLB ต้องไม่ใช้การบีบอัดแบบ Draco

Name
max_colors
Type
integer
ค่าเริ่มต้น 4
Description
จำนวนสีสูงสุดในจานสีผลลัพธ์ ตั้งแต่ 1 ถึง 16 หากต้องการใช้ค่าเริ่มต้น ให้ละเว้นพารามิเตอร์นี้แทนที่จะส่งค่า 0
Name
style
Type
string
ค่าเริ่มต้น realistic
Description
รูปแบบสีของไฟล์ 3MF
ค่าที่ใช้ได้:
- realistic: สุ่มตัวอย่างสีโดยตรงจากเท็กซ์เจอร์ของโมเดลเพื่อรายละเอียดที่สมจริงและละเอียด และทำให้ได้ไฟล์ขนาดใหญ่กว่า
- cartoon: ทำให้สีแบนราบเป็นพื้นที่ที่สม่ำเสมอเพื่อให้ได้ลุคแบบมีสไตล์ และทำให้ได้ไฟล์ขนาดเล็กกว่า
โมเดลต้องมีสี โดย realistic ต้องการเท็กซ์เจอร์สีพื้นฐานเพียงชุดเดียว ที่มี UV บนทุกส่วนของเมช ส่วน cartoon ยอมรับสีจุดยอด (vertex colors) ได้ด้วย Meshy จะปฏิเสธโมเดลที่ไม่มีเท็กซ์เจอร์ (สีขาว) ดูที่ model_missing_texture
Name
max_depth
Type
integer
ค่าเริ่มต้น 4
Description
ระดับความลึกของการแบ่งย่อย (subdivision depth) ที่ Meshy ใช้ในการสุ่มตัวอย่างสีเท็กซ์เจอร์ลงบนเมช ตั้งแต่ 3 ถึง 6 ค่า 0 มีความหมายเหมือนกับการละเว้นพารามิเตอร์นี้ ค่าที่สูงกว่าจะจับรายละเอียดสีได้ละเอียดกว่า และทำให้ได้ไฟล์ขนาดใหญ่กว่า มีเพียงรูปแบบ realistic เท่านั้นที่ใช้พารามิเตอร์นี้ ส่วน cartoon จะไม่สนใจค่านี้
Name
printer_brand
Type
string
ค่าเริ่มต้น bambu
Description
แบรนด์เครื่องพิมพ์ที่ Meshy จะเขียนพรีเซ็ตสไลเซอร์ลงในไฟล์ 3MF จากนั้นไฟล์จะเปิดในสไลเซอร์ของแบรนด์นั้นพร้อมเครื่องพิมพ์ เส้นใย (filament) และโปรไฟล์กระบวนการที่ตรงกัน พรีเซ็ตจะใช้เครื่องพิมพ์เริ่มต้นของแบรนด์ พร้อมหัวฉีดขนาด 0.4 มม.
ค่าที่ใช้ได้:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
ค่าอื่นใดนอกเหนือจากนี้จะคืนค่า 400

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

ฟิลด์ result ของการตอบกลับจะเก็บ ID ของงาน Multi-Color Print ใหม่

รูปแบบความล้มเหลว

Name
400 - Bad Request
Description
คำขอไม่สามารถทำงานได้ ข้อความแสดงข้อผิดพลาดจะบอกว่าพบปัญหาใด ตัวอย่างเช่น:
- พารามิเตอร์ขาดหาย: ไม่ได้ส่งทั้ง model_url และ input_task_id
- รูปแบบโมเดลไม่ถูกต้อง: ไฟล์ model_url ไม่ใช่ไฟล์ .glb หรือ .fbx
- URL ไม่สามารถเข้าถึงได้: Meshy ไม่สามารถดาวน์โหลดไฟล์ model_url ได้
- ไฟล์โมเดลมีขนาดใหญ่เกินไป: ไฟล์ model_url มีขนาดเกิน 400 MB จาก URL แบบ http หรือ https หรือเกิน 100 MB ในรูปแบบ Data URI
- จำนวนหน้ามากเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และมีหน้ามากกว่า 8,000,000 หน้า ให้ลดจำนวนหน้าแล้วส่งไฟล์อีกครั้ง
- ASCII FBX เกิน 100 MB: ไฟล์ model_url เป็น ASCII FBX ที่มีขนาดเกิน 100 MB ให้ส่งเป็น binary FBX หรือ GLB แทน
- ไฟล์โมเดลอ่านไม่ได้: ไฟล์ model_url มีขนาดเกิน 100 MB และ Meshy ไม่สามารถอ่านส่วนหัวของไฟล์ได้ เช่น เป็น GLB ที่บีบอัดแบบ Draco หรือ binary FBX ที่เก่ากว่า 7.1
- ส่วนหัวของโมเดลซับซ้อนเกินไป: ไฟล์ model_url มีขนาดเกิน 100 MB และส่วนหัวมีเมช โหนด หรือระเบียนมากเกินกว่าจะตรวจสอบได้ ให้ลดจำนวนวัตถุในไฟล์แล้วส่งอีกครั้ง
- งานอินพุตไม่ถูกต้อง: input_task_id ไม่ใช่งานที่สำเร็จ
- จำนวนหน้าในงานอินพุตมากเกินไป: โมเดลของ input_task_id มีหน้ามากกว่า 8,000,000 หน้า ให้รันงานรีเมชกับโมเดลก่อน แล้วส่ง ID ของงานรีเมชแทน
- max_colors ไม่ถูกต้อง: max_colors เป็นค่าติดลบหรือเกิน 16
- style ไม่ถูกต้อง: style ไม่ใช่ realistic หรือ cartoon
- max_depth ไม่ถูกต้อง: max_depth อยู่นอกช่วง 3 ถึง 6 และไม่ใช่ 0
- printer_brand ไม่ถูกต้อง: printer_brand ไม่ใช่หนึ่งในค่าที่ใช้ได้
- ไม่มีแหล่งที่มาของสี: โมเดลขาดสีที่ style ต้องการ โดย realistic ต้องการเท็กซ์เจอร์สีพื้นฐานเพียงชุดเดียว ที่มี UV บนทุกส่วนของเมช ส่วน cartoon ยอมรับเท็กซ์เจอร์สีพื้นฐานหรือสีจุดยอด ให้ใส่เท็กซ์เจอร์ให้โมเดลก่อน หรือใช้ cartoon สำหรับโมเดลที่มีสีจุดยอด Meshy จะตรวจสอบไฟล์อัปโหลด .fbx หลังจากที่งานทำให้เป็นมาตรฐานแล้วเท่านั้น ดังนั้นงานจะล้มเหลวด้วย model_missing_texture แทน
แก้ไขคำขอแล้วส่งอีกครั้ง ดูที่ ข้อผิดพลาด
Name
401 - Unauthorized
Description
API คีย์ขาดหายหรือไม่ถูกต้อง ตรวจสอบ header Authorization
Name
402 - Payment Required
Description
ตัวอย่างเช่น:
- เครดิตไม่เพียงพอ: บัญชีมีเครดิตไม่เพียงพอสำหรับงานนี้ หรือบัญชีถึงขีดจำกัดเครดิตแล้ว ตรวจสอบยอดเครดิตคงเหลือของคุณ แล้วลองใหม่
- แผนฟรี: การสร้างงานต้องใช้แผนแบบชำระเงิน อัปเกรดแผนของคุณในการตั้งค่าการสมัครสมาชิก แล้วลองใหม่
Name
403 - Forbidden
Description
input_task_id เป็นโมเดลแบบนูนต่ำ (bas-relief) ซึ่งเอนด์พอยต์นี้ไม่สามารถพิมพ์ได้ ข้อความคือ This model type does not support this operation ให้ส่งโมเดลอื่น
Name
404 - Not Found
Description
input_task_id ไม่ตรงกับงานใดของคุณ ตรวจสอบ ID ของงานแล้วส่งคำขออีกครั้ง
Name
429 - Too Many Requests
Description
คุณเกินขีดจำกัดอัตราการใช้งานแล้ว กรุณารอสักครู่แล้วลองใหม่ ดูที่ การจำกัดอัตรา

GET/openapi/v1/print/multi-color/:id

รับงานการพิมพ์หลายสี

ส่งคืนงานการพิมพ์หลายสีตามรหัสงาน (ID)

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

พารามิเตอร์

Name
id
Type
path
Description
รหัสงานจากการตอบกลับของการสร้าง

ส่งคืนค่า

อ็อบเจ็กต์งานการพิมพ์หลายสี

DELETE/openapi/v1/print/multi-color/:id

ลบงานการพิมพ์หลายสี

ลบงานการพิมพ์หลายสีอย่างถาวร รวมถึงโมเดลและข้อมูลของงานนั้น คุณไม่สามารถยกเลิกการลบได้

Request

DELETE

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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

พารามิเตอร์ของพาธ

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

สถานะของงาน

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

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

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

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

200 OK เมื่อลบงานสำเร็จ หรือ 409 Conflict เมื่องานมีสถานะ IN_PROGRESS

GET/openapi/v1/print/multi-color

แสดงรายการงานพิมพ์หลายสี

ส่งคืนรายการงานการพิมพ์หลายสีของคุณ

Request

GET

/openapi/v1/print/multi-color

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,
    "expires_at": 1700259201000,
    "task_error": null,
  "consumed_credits": 10
  }
]

พารามิเตอร์

Name
page_num
Type
integer
ค่าเริ่มต้น 1
Description
หมายเลขหน้าที่ต้องการให้ส่งคืน หมายเลขหน้าเริ่มต้นที่ 1
Name
page_size
Type
integer
ค่าเริ่มต้น 10
Description
จำนวนงานต่อหน้า สูงสุด 100
Name
sort_by
Type
string
Description
ลำดับการเรียง
ค่าที่ใช้ได้:
- +created_at: เก่าที่สุดก่อน
- -created_at: ใหม่ที่สุดก่อน

ค่าที่ส่งคืน

รายการแบบแบ่งหน้าของออบเจ็กต์งานพิมพ์หลายสี

GET/openapi/v1/print/multi-color/:id/stream

สตรีมงาน Multi-Color Print

สตรีมการอัปเดตของงาน Multi-Color Print ในรูปแบบ Server-Sent Events (SSE)

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

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.
// These examples are shortened. Each event holds 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-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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานจากการตอบกลับตอนสร้างงาน

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

สตรีมของอ็อบเจกต์งาน Multi-Color Print ในรูปแบบ Server-Sent Events

แต่ละอีเวนต์จะเก็บอ็อบเจกต์งานทั้งหมด ในรูปแบบเดียวกับที่เอนด์พอยต์ Get ส่งกลับมา ขณะที่งานมีสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์ต่าง ๆ จะยังไม่มีค่า

The Multi-Color Print task object

อ็อบเจกต์งาน Multi-Color Print อธิบายการแปลงโมเดล 3D หนึ่งครั้งไปเป็นไฟล์ 3MF หลายสี โดยเก็บสถานะ progress และไฟล์ 3MF เมื่อการทำงานสำเร็จ

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

Name
id
Type
string
Description
รหัสของงาน ให้ถือว่าเป็นสตริงที่ไม่มีความหมายตายตัว และอย่าอ้างอิงรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งเป็น print-multi-color เสมอ
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดโมเดลที่พิมพ์แล้ว หนึ่งรายการต่อหนึ่งรูปแบบไฟล์ รูปแบบที่งานไม่ได้สร้างขึ้นจะไม่มีคีย์นั้นปรากฏ แทนที่จะเป็นสตริงว่างเปล่า
- Name
  3mf
  Type
  string
  Description
  ไฟล์ 3MF หลายสี
Name
progress
Type
integer
Description
งานเสร็จไปแล้วเท่าไร แสดงเป็นเปอร์เซ็นต์ โดยจะเป็น 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
เวลาที่สร้างงาน หน่วยเป็นมิลลิวินาทีแบบ Unix
Name
started_at
Type
timestamp
Description
เวลาที่งานเริ่มทำงาน หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่างานจะเริ่ม
Name
finished_at
Type
timestamp
Description
เวลาที่งานเสร็จสิ้น หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่างานจะเสร็จสิ้น
Name
expires_at
Type
timestamp
Description
เวลาที่ผลลัพธ์ของงานหมดอายุ หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น 0 จนกว่างานจะเสร็จสิ้น
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดเมื่องานล้มเหลว ดู ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่งานนี้ใช้ไป จะปรากฏเมื่อสถานะเป็น PENDING, IN_PROGRESS หรือ SUCCEEDED และจะเป็น 0 สำหรับงานที่ FAILED เนื่องจาก Meshy จะคืนเครดิตเมื่องานล้มเหลว