API ซ่อมความสามารถในการพิมพ์

ซ่อมโมเดล 3D เพื่อความสามารถในการพิมพ์แบบ FDM — แก้ไขขอบ non-manifold, หน้าเสื่อม, รู และปัญหา topology อื่น ๆ เพื่อให้เมชพร้อมสำหรับการพิมพ์

POST/openapi/v1/print/repair

สร้างงานซ่อมความสามารถในการพิมพ์

เอนด์พอยต์นี้สร้างงานซ่อมความสามารถในการพิมพ์ใหม่ งานนี้จะดำเนินการซ่อม topology บนโมเดล 3D และคืนค่าเวอร์ชันที่ไม่มีรอยรั่ว (watertight) และพร้อมสำหรับการพิมพ์

รูปแบบผลลัพธ์จะตรงกับรูปแบบอินพุต หากคุณส่ง .stl ผ่าน model_url ผลลัพธ์ model_urls.stl ในการตอบกลับจะเก็บเมชที่ซ่อมแล้ว และฟิลด์รูปแบบอื่นจะว่างเปล่า พาธ input_task_id จะอ่าน GLB ของงานต้นทางเสมอ ดังนั้นผลลัพธ์จึงเป็น .glb

พารามิเตอร์

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

เท็กซ์เจอร์ที่มีอยู่จะถูกลบออกระหว่างการซ่อมเนื่องจากการเปลี่ยนแปลงจีออเมทรี หากต้องการเพิ่มเท็กซ์เจอร์กลับเข้าไป ให้ใช้ Retexture API กับโมเดลที่ซ่อมแล้ว

Name
input_task_id
Type
string
จำเป็น
Description
ID ของงานที่สำเร็จซึ่งคุณเป็นเจ้าของ ประเภทงานที่รองรับ: รูปภาพเป็น 3D, หลายรูปเป็น 3D, ข้อความเป็น 3D, รีเมช, และ รีเท็กซ์เจอร์ งานนั้นต้องมีสถานะเป็น SUCCEEDED และต้องสร้างเอเซ็ต GLB ไว้แล้ว

Name
model_url
Type
string
จำเป็น
Description
URL ของโมเดล 3D ที่จะซ่อม รูปแบบที่รองรับ: .glb, .gltf, .obj, .fbx, .stl ขนาดไฟล์สูงสุด: 100 MB ต้องใช้ http, https, หรือ data: URL (data URL จะข้ามการตรวจสอบนามสกุลไฟล์)

Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true งานจะเรนเดอร์ตัวอย่างพื้นหลังโปร่งใส (RGBA) เพิ่มเติม และคืนค่าเป็น alpha_thumbnail_url ในการตอบกลับ GET ฟิลด์ thumbnail_url ที่มีอยู่เดิมจะไม่เปลี่ยนแปลง

ผลลัพธ์ที่คืนค่า

คุณสมบัติ result ของการตอบกลับจะมี id ของงานซ่อมความสามารถในการพิมพ์ที่สร้างขึ้นใหม่

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

Name
400 - Bad Request
Description
คำขอไม่เป็นที่ยอมรับ สาเหตุทั่วไปได้แก่:
- ขาดพารามิเตอร์: ไม่ได้ระบุทั้ง input_task_id และ model_url
- UUID ไม่ถูกต้อง: input_task_id ไม่ใช่ UUID ที่ถูกต้อง
- URL โมเดลไม่ถูกต้อง: model_url มีรูปแบบไม่ถูกต้อง ใช้สคีมที่ไม่รองรับ หรือมีนามสกุลไฟล์ที่ไม่รองรับ
- ไฟล์โมเดลมีขนาดใหญ่เกินไป: เนื้อหาของ model_url มีขนาดเกิน 100 MB
- งานยังไม่สำเร็จ: งานที่อ้างอิงยังอยู่ระหว่างรอ กำลังดำเนินการ หรือล้มเหลว
- ไม่มี GLB: งานที่อ้างอิงไม่มีเอเซ็ต GLB ให้ซ่อม
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
สาเหตุทั่วไป:
- แผนฟรี: การสร้างงานต้องใช้แผนแบบชำระเงิน อัปเกรดได้ที่หน้าการสมัครสมาชิก
- เครดิตไม่เพียงพอ: ถึงขีดจำกัดเครดิตของพื้นที่ทำงานแล้ว
Name
404 - Not Found
Description
งานที่อ้างอิงไม่มีอยู่ หรือเป็นของผู้ใช้รายอื่น
Name
429 - Too Many Requests
Description
คุณเกินโควตางานที่รอดำเนินการหรือการจำกัดอัตราแล้ว

Request

POST

/openapi/v1/print/repair

# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.stl"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/repair/:id

เรียกดูงานซ่อมความสามารถในการพิมพ์

เอนด์พอยต์นี้ใช้เรียกดูงานซ่อมความสามารถในการพิมพ์โดยใช้ ID ของงานนั้น

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานซ่อมความสามารถในการพิมพ์ที่ต้องการเรียกดู

สิ่งที่ได้รับกลับมา

Repair Printability Task Object โดยส่วน model_urls จะยังว่างเปล่าจนกว่างานจะมีสถานะ SUCCEEDED และจะมีเพียงฟิลด์ model_urls ที่ตรงกับรูปแบบไฟล์ที่ป้อนเข้ามาเท่านั้นที่จะถูกเติมข้อมูล

Request

GET

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

curl https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

DELETE/openapi/v1/print/repair/:id

ลบงานซ่อมความสามารถในการพิมพ์

เอนด์พอยต์นี้จะลบงานซ่อมความสามารถในการพิมพ์และผลลัพธ์ที่ซ่อมแล้วอย่างถาวร การกระทำนี้ไม่สามารถย้อนกลับได้

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

Name
id
Type
path
Description
ID ของงานซ่อมความสามารถในการพิมพ์ที่ต้องการลบ

สถานะของงาน

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

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

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

สิ่งที่ส่งกลับ

ส่งกลับ 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่องานอยู่ในสถานะ IN_PROGRESS

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/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."
}

GET/openapi/v1/print/repair

รายการงานซ่อมความสามารถในการพิมพ์

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงานซ่อมความสามารถในการพิมพ์ได้

พารามิเตอร์

แอตทริบิวต์ที่ไม่บังคับ

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: เรียงลำดับตามเวลาที่สร้างจากมากไปน้อย

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

ส่งกลับรายการแบบแบ่งหน้าของ Repair Printability Task Objects

Request

GET

/openapi/v1/print/repair

curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]

GET/openapi/v1/print/repair/:id/stream

สตรีมงานซ่อมความสามารถในการพิมพ์

เอนด์พอยต์นี้จะสตรีมข้อมูลอัปเดตแบบเรียลไทม์สำหรับงานซ่อมความสามารถในการพิมพ์โดยใช้ Server-Sent Events (SSE)

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงานซ่อมความสามารถในการพิมพ์ที่ต้องการสตรีม

สิ่งที่ส่งกลับ

ส่งกลับสตรีมของ Repair Printability Task Objects ในรูปแบบ Server-Sent Events

ทุกเฟรมจะบรรจุอ็อบเจกต์งานฉบับเต็มสำหรับขั้นตอนนั้น ๆ — ในรูปแบบเดียวกับที่ Get endpoint ส่งกลับ — ดังนั้นในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์จะยังไม่ถูกกรอกข้อมูล (null, [] หรือ {}) และ finished_at จะเป็น null ส่วนบล็อก model_urls จะถูกส่งก็ต่อเมื่องานมีสถานะถึง SUCCEEDED แล้วเท่านั้น

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/repair/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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

The Repair Printability Task Object

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID สำหรับ id ของงานในรายละเอียดการทำงานจริง คุณไม่ควรตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงานซ่อมความสามารถในการพิมพ์ ค่าคือ print-repair
Name
status
Type
string
Description
สถานะของงาน ค่าที่เป็นไปได้คือ PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
progress ของงาน หากงานยังไม่เริ่มต้น ค่านี้จะเป็น 0 เมื่องานสำเร็จแล้ว ค่านี้จะเปลี่ยนเป็น 100
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
expires_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของงานจะหมดอายุจากระบบ หน่วยเป็นมิลลิวินาที ค่าเป็น 0 หากงานยังไม่เสร็จสิ้น
Name
task_error
Type
object
Description
ข้อมูลข้อผิดพลาดหากงานล้มเหลว คุณสมบัตินี้จะเป็น null หากงานไม่ล้มเหลว ดู ข้อผิดพลาด สำหรับรายละเอียดเพิ่มเติม
- Name
  message
  Type
  string
  Description
  ข้อความข้อผิดพลาดที่อธิบายว่าเกิดปัญหาอะไรขึ้น
Name
model_urls
Type
object
Description
URL ที่สามารถดาวน์โหลดโมเดล 3D ที่ซ่อมแล้ว จะมีเพียงฟิลด์ที่ตรงกับรูปแบบอินพุตเท่านั้นที่ถูกเติมข้อมูล ฟิลด์รูปแบบอื่นจะเป็นสตริงว่าง
- Name
  glb
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลด GLB ที่ซ่อมแล้ว ถูกเติมข้อมูลเมื่ออินพุตเป็น GLB หรือเมื่อใช้ input_task_id
- Name
  gltf
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลด GLTF ที่ซ่อมแล้ว ถูกเติมข้อมูลเมื่ออินพุตเป็นการอัปโหลด GLTF
- Name
  fbx
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลด FBX ที่ซ่อมแล้ว ถูกเติมข้อมูลเมื่ออินพุตเป็นการอัปโหลด FBX
- Name
  obj
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลด OBJ ที่ซ่อมแล้ว ถูกเติมข้อมูลเมื่ออินพุตเป็นการอัปโหลด OBJ
- Name
  stl
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลด STL ที่ซ่อมแล้ว ถูกเติมข้อมูลเมื่ออินพุตเป็นการอัปโหลด STL
- Name
  usdz
  Type
  string
  Description
  สงวนไว้สำหรับผลลัพธ์ USDZ เป็นสตริงว่างเสมอสำหรับงานซ่อมความสามารถในการพิมพ์
- Name
  3mf
  Type
  string
  Description
  สงวนไว้สำหรับผลลัพธ์ 3MF เป็นสตริงว่างเสมอสำหรับงานซ่อมความสามารถในการพิมพ์
- Name
  mtl
  Type
  string
  Description
  สงวนไว้สำหรับผลลัพธ์ MTL เป็นสตริงว่างเสมอสำหรับงานซ่อมความสามารถในการพิมพ์
Name
thumbnail_url
Type
string
Description
URL ของภาพตัวอย่างที่เรนเดอร์จากโมเดลที่ซ่อมแล้ว
Name
alpha_thumbnail_url
Type
string
Description
URL ที่สามารถดาวน์โหลดเวอร์ชันพื้นหลังโปร่งใส (RGBA) ของ thumbnail_url จะปรากฏเฉพาะเมื่อสร้างงานด้วย alpha_thumbnail: true และการเรนเดอร์ภาพตัวอย่างแบบโปร่งใสสำเร็จ มิฉะนั้นฟิลด์นี้จะถูกละไว้
Name
texture_urls
Type
array
Description
เป็นอาร์เรย์ว่างเสมอ การซ่อมจะรักษาเฉพาะจีออเมทรีของอินพุตเท่านั้นและไม่ทำการเบค texture ใหม่
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ใช้ไปสำหรับงานนี้ 10 เมื่องานถึงสถานะ SUCCEEDED แล้ว คืนค่า 0 สำหรับงานที่เป็น FAILED (เครดิตจะได้รับการคืนเมื่อล้มเหลว)

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}