프린팅 가능성 분석 API

3D 모델의 프린팅 가능성을 분석합니다 — 수밀성, 부피, 홀, 비매니맨폴드 에지, 퇴화 면을 확인합니다. 선택적으로 프린팅하려는 크기에서 벽 두께도 확인할 수 있습니다.

POST/openapi/v1/print/analyze

프린팅 가능성 분석 작업 삭제

이 엔드포인트는 프린팅 가능성 분석 작업과 캐시된 결과를 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

Name
id
Type
path
Description
삭제할 프린팅 가능성 분석 작업의 ID입니다.

작업 상태

아직 PENDING 상태인 작업은 삭제되며, 생성 시 소비된 크레딧은 환불됩니다.

이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업에 대한 크레딧은 환불되지 않으므로, 실행 도중에 삭제하면 크레딧과 결과를 모두 잃게 됩니다. SUCCEEDED, FAILED 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED 또는 CANCELED)의 작업은 환불 없이 삭제됩니다.

반환값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS 상태일 때는 409 Conflict를 반환합니다.

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부터 시작하며 기본값은 1입니다.
Name
page_size
Type
integer
Description
페이지 크기 제한입니다. 기본값은 10개 항목이며, 최대 허용값은 100개 항목입니다.
Name
sort_by
Type
string
Description
정렬 기준 필드입니다. 사용 가능한 값:
- +created_at: 생성 시간 오름차순으로 정렬합니다.
- -created_at: 생성 시간 내림차순으로 정렬합니다.

반환값

Analyze Printability Task 객체의 페이지네이션 목록을 반환합니다.

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 형태로 반환합니다.

모든 프레임은 해당 단계의 전체 작업 객체를 담고 있습니다 — 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
}

프린팅 가능성 분석 태스크 객체

Name
id
Type
string
Description
태스크의 고유 식별자입니다. 구현 세부사항으로 태스크 id에 k-정렬 가능한 UUID를 사용하고 있지만, id의 형식에 대해서는 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
프린팅 가능성 분석 태스크의 유형입니다. 값은 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
프린팅 가능성 평가 결과입니다. 태스크가 SUCCEEDED에 도달하기 전까지는 null입니다.
- Name
  _version
  Type
  string
  Description
  프린팅 가능성 결과의 스키마 버전입니다. 현재는 v1입니다.
- Name
  status
  Type
  string
  Description
  전체 상태입니다. 다음 중 하나입니다:
  
  healthy: 오류도 경고도 없음.
  
  warning: 경고가 하나 이상 있고 오류는 없음.
  
  error: 오류가 하나 이상 있음.
  
  unknown: 모델을 분석할 수 없었음.
  
  벽 두께를 확인한 경우, 이는 위의 검사들과 thin_walls.status 중 더 나쁜 쪽입니다. 나쁜 순서대로: error, warning, unknown, healthy.
- Name
  issue_count
  Type
  integer
  Description
  문제의 총 개수이며, error_count + warning_count와 같습니다.
- Name
  error_count
  Type
  integer
  Description
  오류 수준 문제의 개수입니다. 오류는 모델이 워터타이트하지 않거나, 부피가 0 이하이거나, 비매니폴드 에지가 있을 때 발생합니다. 벽 두께를 확인한 경우, 너무 얇은 벽(thin_walls.status가 error인 경우)은 오류 하나로 추가로 집계됩니다.
- 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
  비매니폴드 에지의 개수입니다.
  Name
  degenerate_faces
  Type
  integer
  Description
  퇴화 면(면적이 0이거나 유효하지 않은 면)의 개수입니다.
  Name
  holes
  Type
  integer
  Description
  메시 내 구멍(경계 루프)의 개수입니다.
- Name
  intended_print
  Type
  object
  Description
  벽 두께 검사에 사용된 프린터 및 크기입니다. 벽 두께를 확인한 경우에만 존재합니다.
  Name
  printer_type
  Type
  string
  Description
  fdm, sla, 또는 full_color입니다.
  Name
  height_mm
  Type
  number
  Description
  프린트물이 높이로 크기가 지정된 경우, 밀리미터 단위의 프린트 높이입니다. 그렇지 않으면 null입니다.
  Name
  longest_side_mm
  Type
  number
  Description
  프린트물의 가장 긴 변의 길이이며, 밀리미터 단위입니다. 높이로 크기가 지정된 경우, 모델의 비율로부터 계산됩니다.
  Name
  wall_thickness_mm
  Type
  number
  Description
  printer_type에 대한 최소 벽 두께이며, 밀리미터 단위입니다. 이보다 얇은 벽은 너무 얇은 것으로 보고됩니다.
  Name
  dimensions_mm
  Type
  array
  Description
  프린트물의 [너비, 깊이, 높이]이며, 밀리미터 단위입니다. 높이는 height_mm과 밀리미터의 일부만큼 다를 수 있습니다. GLB가 아닌 입력이거나 모델의 크기를 확인할 수 없는 경우 null입니다.
- Name
  thin_walls
  Type
  object
  Description
  벽 두께 결과입니다. 벽 두께를 확인한 경우에만 존재합니다.
  Name
  thin_area_ratio
  Type
  number
  Description
  intended_print.wall_thickness_mm보다 얇은 표면의 비율이며, 0에서 1 사이입니다. 모델을 측정할 수 없는 경우 null입니다.
  Name
  has_thin_walls
  Type
  boolean
  Description
  표면의 일부가 너무 얇은 경우 true입니다. 날카로운 모서리만으로도 이 값이 설정될 수 있으므로, 벽을 두껍게 해야 하는지 판단할 때는 status를 사용하세요. 모델을 측정할 수 없는 경우 null입니다.
  Name
  status
  Type
  string
  Description
  벽 두께 판정 결과입니다. 다음 중 하나입니다:
  
  healthy: 표면의 5% 이하가 너무 얇음.
  
  error: 표면의 5% 초과가 너무 얇음. 벽을 두껍게 하려면 이 태스크의 id를 input_task_id로 프린팅 가능성 복구에 전달하세요(.stl, .fbx, 또는 .gltf인 model_url의 경우, 대신 파일 자체를 model_url로 전송하세요).
  
  unknown: 모델을 측정할 수 없었음. 벽 두께 검사 자체가 실패하면 태스크는 FAILED로 종료됩니다.
- Name
  evaluated_at
  Type
  timestamp
  Description
  분석이 계산된 시점의 타임스탬프이며, 에포크 이후 밀리초 단위입니다.
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
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}

프린팅 가능성 분석 API

프린팅 가능성 분석 작업 생성

파라미터

반환 값

실패 모드

Request

Response

프린팅 가능성 분석 작업 조회

Parameters

Returns

Request

Response

Response (wall thickness checked)

프린팅 가능성 분석 작업 삭제

경로 매개변수

작업 상태

반환값

Request

Response

List Analyze Printability Tasks

매개변수

선택 속성

반환값

Request

Response

프린팅 가능성 분석 작업 스트리밍

매개변수

반환값

Request

Response Stream

프린팅 가능성 분석 태스크 객체

The Analyze Printability Task Object

The Analyze Printability Task Object (wall thickness checked)