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

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

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

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

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

พารามิเตอร์

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

  • Name
    model_url
    Type
    string
    จำเป็น
    Description

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

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

พร็อพเพอร์ตี้ result ของการตอบกลับประกอบด้วย id ของงานวิเคราะห์ความสามารถในการพิมพ์ที่สร้างขึ้นใหม่

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

  • Name
    400 - Bad Request
    Description

    คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:

    • ขาดพารามิเตอร์: ไม่ได้ระบุทั้ง input_task_id และ model_url
    • UUID ไม่ถูกต้อง: input_task_id ไม่ใช่ UUID ที่ถูกต้อง
    • URL โมเดลไม่ถูกต้อง: model_url มีรูปแบบผิด ใช้ scheme ที่ไม่รองรับ หรือมีนามสกุลไฟล์ที่ไม่รองรับ
    • ไฟล์โมเดลมีขนาดใหญ่เกินไป: เนื้อหาของ model_url มีขนาดเกิน 100 MB
    • งานยังไม่สำเร็จ: งานที่อ้างอิงยังอยู่ระหว่างรอดำเนินการ กำลังดำเนินการ หรือล้มเหลว
  • Name
    401 - Unauthorized
    Description

    การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ

  • Name
    403 - Forbidden
    Description

    งานนี้มีอยู่ แต่เป็นของผู้ใช้รายอื่น

  • Name
    404 - Not Found
    Description

    สาเหตุที่พบบ่อย:

    • งานนี้ไม่มีอยู่หรือถูกลบไปแล้ว
    • งานนี้ใช้โมเดลที่เก่ากว่า Meshy 6 หรือ mode ของงานไม่สร้างแอสเซท 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 ของงานวิเคราะห์ความสามารถในการพิมพ์ที่ต้องการเรียกดู

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

Analyze Printability Task Object โดยฟิลด์ 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 ของงานวิเคราะห์ความสามารถในการพิมพ์ที่ต้องการลบ

สถานะของงาน

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

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

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

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

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

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

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

List Analyze Printability Tasks

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

พารามิเตอร์

แอตทริบิวต์ที่ไม่จำเป็น

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

ผลลัพธ์ที่ส่งกลับ

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

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

Stream an Analyze Printability Task

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

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

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

ส่งคืนสตรีมของ Analyze Printability Task Objects ในรูปแบบ Server-Sent Events

ทุกเฟรมจะมีข้อมูลออบเจ็กต์ของงานทั้งหมดสำหรับขั้นตอนนั้น ๆ — รูปแบบเดียวกับที่ เอนด์พอยต์ Get ส่งคืน — ดังนั้นในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์จะยังไม่มีข้อมูล (null, [] หรือ {}) และ finished_at จะเป็น null ส่วนบล็อก 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.
// 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-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
}

The Analyze Printability Task Object

  • Name
    id
    Type
    string
    Description

    ตัวระบุที่ไม่ซ้ำกันสำหรับ task นี้ แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id ในเชิงรายละเอียดการ implementation แต่คุณไม่ควรตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id

  • Name
    type
    Type
    string
    Description

    ประเภทของ task วิเคราะห์ความสามารถในการพิมพ์ ค่านี้คือ print-analyze

  • Name
    status
    Type
    string
    Description

    สถานะของ task ค่าที่เป็นไปได้คือค่าใดค่าหนึ่งจาก PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED

  • Name
    progress
    Type
    integer
    Description

    progress ของ task หาก task ยังไม่เริ่ม พร็อพเพอร์ตี้นี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100

  • 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
    expires_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของ task นี้จะหมดอายุออกจากระบบ หน่วยเป็นมิลลิวินาที เป็น 0 หาก task ยังไม่เสร็จสิ้น

  • Name
    task_error
    Type
    object
    Description

    ข้อมูลข้อผิดพลาดหาก task ล้มเหลว พร็อพเพอร์ตี้นี้จะเป็น null หาก task ไม่ได้ล้มเหลว ดู ข้อผิดพลาด สำหรับรายละเอียดเพิ่มเติม

    • Name
      message
      Type
      string
      Description

      ข้อความข้อผิดพลาดที่อธิบายว่าเกิดอะไรผิดพลาด

  • Name
    printability
    Type
    object
    Description

    ผลลัพธ์การประเมินความสามารถในการพิมพ์ เป็น null จนกว่า task จะถึงสถานะ 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

      จำนวนปัญหาระดับข้อผิดพลาด ข้อผิดพลาดจะถูกแจ้งเมื่อโมเดลไม่กันน้ำ (watertight) มีปริมาตรที่ไม่เป็นบวก หรือมีขอบ 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

        จำนวนรู (boundary loops) ในเมช

    • 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
}