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

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

POST/openapi/v1/print/repair

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

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

รูปแบบผลลัพธ์จะตรงกับรูปแบบอินพุต หากคุณส่ง .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 URLs ข้ามการตรวจสอบส่วนขยาย)

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 ของงานซ่อมความสามารถในการพิมพ์ที่ต้องการดึง

ผลลัพธ์

วัตถุงานซ่อมความสามารถในการพิมพ์ บล็อก 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

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

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

พารามิเตอร์ในเส้นทาง

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

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

ส่งกลับ 200 OK เมื่อสำเร็จ

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

// Returns 200 Ok on success.

GET/openapi/v1/print/repair

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

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

พารามิเตอร์

คุณสมบัติเสริม

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

การส่งคืน

ส่งคืนรายการที่แบ่งหน้าของ วัตถุงานซ่อมความสามารถในการพิมพ์

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
ตัวระบุเฉพาะสำหรับงานซ่อมความสามารถในการพิมพ์ที่จะสตรีม

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

ส่งคืนสตรีมของ วัตถุงานซ่อมความสามารถในการพิมพ์ เป็น Server-Sent Events

สำหรับงานที่อยู่ในสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะรวมเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น บล็อก 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.
// 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-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
}

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

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับงานนี้ แม้ว่าเราจะใช้ 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
ความคืบหน้าของงาน หากงานยังไม่ได้เริ่มต้น คุณสมบัตินี้จะเป็น 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
URLs สำหรับดาวน์โหลดโมเดล 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
}