프린팅 가능성 분석 API

3D 모델의 FDM 프린팅 가능성을 분석합니다 — 수밀성, 부피, 구멍, 비매니폴드 에지, 퇴화 면.

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 이상(포함 Meshy 7)을 사용해야 하며 SUCCEEDED 상태여야 합니다.

Name
model_url
Type
string
필수
Description
분석할 3D 모델의 URL입니다. 지원되는 형식: .glb, .gltf, .obj, .fbx, .stl. 최대 파일 크기: 100 MB. http, https, 또는 data: URL을 사용해야 합니다(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보다 오래된 모델을 사용하거나 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입니다.

반환값

프린팅 가능성 분석 작업 객체. 작업이 SUCCEEDED 상태에 도달할 때까지 printability 필드는 null입니다.

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부터 시작하며 기본값은 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
작업의 고유 식별자입니다. 작업 ID에 대해 k-sortable 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
작업의 진행 상황입니다. 작업이 아직 시작되지 않은 경우, 이 속성은 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: 모델을 분석할 수 없습니다.
- Name
  issue_count
  Type
  integer
  Description
  문제의 총 수입니다. error_count + warning_count와 같습니다.
- Name
  error_count
  Type
  integer
  Description
  오류 수준 문제의 수입니다. 모델이 비매니폴드 에지를 가지고 있거나 비양수 부피를 가지거나 매니폴드가 아닌 에지를 가질 때 오류가 발생합니다.
- 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
  퇴화 면(영역이 없거나 유효하지 않은 면)의 수입니다.
  Name
  holes
  Type
  integer
  Description
  메시의 구멍(경계 루프)의 수입니다.
- 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
}