API วิเคราะห์ความสามารถในการพิมพ์

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

POST/openapi/v1/print/analyze

สร้างงานวิเคราะห์ความสามารถในการพิมพ์

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

หากงานอินพุตมีความสามารถในการพิมพ์ที่แคชไว้แล้ว งานที่ส่งคืนจะพร้อมใช้งานทันที และการเรียก GET ครั้งแรกกับงานนั้นจะส่งคืนผลการวิเคราะห์โดยไม่ต้องผ่านเวิร์กเกอร์

พารามิเตอร์

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

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

Name
model_url
Type
string
จำเป็น
Description
URL ของโมเดล 3D ที่ต้องการวิเคราะห์ รูปแบบที่รองรับ: .glb, .gltf, .obj, .fbx, .stl ขนาดไฟล์สูงสุด: 100 MB ต้องใช้ URL แบบ http, https หรือ data: (data 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
- งานยังไม่สำเร็จ: งานที่อ้างอิงยังอยู่ระหว่างรอดำเนินการ กำลังดำเนินการ หรือดำเนินการล้มเหลว
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
403 - Forbidden
Description
งานมีอยู่แต่เป็นของผู้ใช้คนอื่น
Name
404 - Not Found
Description
สาเหตุที่พบบ่อย:
- งานไม่มีอยู่หรือถูกลบไปแล้ว
- งานใช้โมเดลที่เก่ากว่า Meshy 6 หรือ mode ของงานไม่ได้สร้าง asset 3D
- ไฟล์โมเดลพื้นฐานไม่พร้อมใช้งานในพื้นที่จัดเก็บอีกต่อไป
Name
429 - Too Many Requests
Description
คุณใช้โควตางานที่รอดำเนินการหรือการจำกัดอัตราเกินแล้ว

Request

POST

/openapi/v1/print/analyze

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

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

Response

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

GET/openapi/v1/print/analyze/:id

เรียกดูงานวิเคราะห์ความสามารถในการพิมพ์

เอนด์พอยต์นี้เรียกดูงานวิเคราะห์ความสามารถในการพิมพ์ตาม ID ของงาน

พารามิเตอร์

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

ส่งคืน

ออบเจ็กต์งานวิเคราะห์ความสามารถในการพิมพ์ ฟิลด์ printability จะเป็น null จนกว่างานจะถึงสถานะ SUCCEEDED

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

ลบงานวิเคราะห์ความสามารถในการพิมพ์

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

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

Name
id
Type
path
Description
ID ของงานวิเคราะห์ความสามารถในการพิมพ์ที่จะลบ

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

ส่งคืน 200 OK เมื่อสำเร็จ

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/analyze

รายการงานวิเคราะห์ความสามารถในการพิมพ์

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

พารามิเตอร์

แอตทริบิวต์เสริม

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/analyze

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

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

สตรีมงานวิเคราะห์ความสามารถในการพิมพ์

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

พารามิเตอร์

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

การส่งคืน

ส่งคืนสตรีมของ อ็อบเจ็กต์งานวิเคราะห์ความสามารถในการพิมพ์ ในรูปแบบ Server-Sent Events

สำหรับงาน PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะรวมเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น บล็อก printability จะถูกส่งเมื่อทำงานถึงสถานะ SUCCEEDED แล้วเท่านั้น

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/analyze/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-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

อ็อบเจ็กต์งานวิเคราะห์ความสามารถในการพิมพ์

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับงาน แม้ว่าเราจะใช้ UUID แบบ k-sortable สำหรับ id ของงานเป็น รายละเอียดการใช้งาน คุณก็ ไม่ควร ตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงาน analyze-printability ค่าคือ print-analyze
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
printability
Type
object
Description
ผลการประเมินความสามารถในการพิมพ์ null จนกว่างานจะถึงสถานะ SUCCEEDED
- Name
  _version
  Type
  string
  Description
  เวอร์ชันสคีมาของผลลัพธ์ความสามารถในการพิมพ์ ปัจจุบันคือ v1
- Name
  status
  Type
  string
  Description
  สถานะโดยรวม หนึ่งใน:
  
  healthy: ไม่มีข้อผิดพลาดและไม่มีคำเตือน
  
  warning: มีคำเตือนอย่างน้อยหนึ่งรายการ ไม่มีข้อผิดพลาด
  
  error: มีข้อผิดพลาดอย่างน้อยหนึ่งรายการ
  
  unknown: ไม่สามารถวิเคราะห์โมเดลได้
- Name
  issue_count
  Type
  integer
  Description
  จำนวนปัญหาทั้งหมด เท่ากับ error_count + warning_count
- Name
  error_count
  Type
  integer
  Description
  จำนวนปัญหาระดับข้อผิดพลาด ข้อผิดพลาดจะถูกแจ้งเมื่อโมเดล ไม่ปิดสนิท, มี ปริมาตรไม่เป็นบวก, หรือมี ขอบ non-manifold
- Name
  warning_count
  Type
  integer
  Description
  จำนวนปัญหาระดับคำเตือน คำเตือนจะถูกแจ้งเมื่อโมเดลมี หน้าเสื่อม หรือ รู
- Name
  metrics
  Type
  object
  Description
  เมตริกจีออเมทรีดิบที่ส่งคืนโดยตัวประเมิน
  Name
  is_watertight
  Type
  boolean
  Description
  true เมื่อเมชไม่มีขอบเขตขอบ (กล่าวคือ ปิดอยู่)
  Name
  volume
  Type
  number
  Description
  ปริมาตรของโมเดลเป็นลูกบาศก์เมตร
  Name
  non_manifold_edges
  Type
  integer
  Description
  จำนวนขอบ non-manifold
  Name
  degenerate_faces
  Type
  integer
  Description
  จำนวนหน้าเสื่อม (หน้าที่มีพื้นที่เป็นศูนย์หรือไม่ถูกต้อง)
  Name
  holes
  Type
  integer
  Description
  จำนวนรู (ลูปขอบเขต) ในเมช
- Name
  evaluated_at
  Type
  timestamp
  Description
  ไทม์สแตมป์ของเวลาที่การวิเคราะห์ถูกคำนวณ เป็นมิลลิวินาทีนับตั้งแต่ epoch
Name
consumed_credits
Type
integer
Description
เป็น 0 เสมอ เอนด์พอยต์นี้ใช้งานฟรี

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}