프린팅 가능성 복구 API

FDM 프린팅 가능성을 위해 3D 모델을 복구합니다 — 비매니폴드 에지, 퇴화 면, 구멍 및 기타 topology 문제를 수정하여 메시를 프린팅할 준비가 된 상태로 만듭니다.

POST/openapi/v1/print/repair

프린팅 가능성 복구 작업 생성

이 엔드포인트는 새로운 프린팅 가능성 복구 작업을 생성합니다. 작업은 3D 모델에 topology 복구를 실행하고 워터타이트하며 프린팅 준비가 완료된 버전을 반환합니다.

출력 형식은 입력 형식과 일치합니다. model_url을 통해 .stl을 제출하면 응답의 model_urls.stl에 복구된 메시가 들어가고 다른 형식 필드는 비어 있게 됩니다. input_task_id 경로는 항상 소스 작업의 GLB를 읽으므로 출력은 .glb입니다.

파라미터

input_task_id 또는 model_url 중 하나만 필수입니다. 둘 다 제공된 경우 input_task_id가 우선순위를 갖습니다.

지오메트리 변경으로 인해 복구 중 기존 텍스처가 제거됩니다. 텍스처를 다시 추가하려면 복구된 모델에 리텍스처 API를 사용하세요.

Name
input_task_id
Type
string
필수
Description
사용자가 소유한 성공한 작업의 ID입니다. 지원되는 작업 유형: 이미지로 3D, 멀티 이미지로 3D, 텍스트로 3D, 리메시, 및 리텍스처. 작업의 상태는 SUCCEEDED여야 하며 GLB 에셋을 생성했어야 합니다.

Name
model_url
Type
string
필수
Description
복구할 3D 모델의 URL입니다. 지원 형식: .glb, .stl, .obj. 최대 파일 크기: 100 MB. http, https 또는 data: URL을 사용해야 합니다(data URL은 확장자 검사를 우회합니다).

Name
alpha_thumbnail
Type
boolean
기본값 false
Description
true로 설정하면 작업이 추가로 미리보기의 투명 배경(RGBA) 버전을 렌더링하고 GET 응답에서 alpha_thumbnail_url로 반환합니다. 기존 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입니다.

반환값

프린팅 가능성 복구 작업 객체. 작업이 SUCCEEDED에 도달할 때까지 model_urls 블록은 비어 있습니다. 입력 형식과 일치하는 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": "",
    "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부터 시작하며 기본값은 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=***",
      "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=***",
    "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
작업의 고유 식별자입니다. 구현 세부 사항으로 작업 id에 k-정렬 가능한 UUID를 사용하지만, id 형식에 대해 어떤 가정도 해서는 안 됩니다.
Name
type
Type
string
Description
프린팅 가능성 복구 작업의 유형입니다. 값은 print-repair입니다.
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
model_urls
Type
object
Description
복구된 3D 모델에 대한 다운로드 가능한 URL입니다. 입력 형식과 일치하는 필드만 채워집니다. 다른 형식 필드는 빈 문자열입니다.
- Name
  glb
  Type
  string
  Description
  복구된 GLB에 대한 다운로드 가능한 URL입니다. 입력이 GLB였거나 input_task_id가 사용된 경우 채워집니다.
- Name
  fbx
  Type
  string
  Description
  FBX 출력을 위해 예약되어 있습니다. 프린팅 가능성 복구 작업에서는 항상 빈 문자열입니다.
- Name
  obj
  Type
  string
  Description
  복구된 OBJ에 대한 다운로드 가능한 URL입니다. 입력이 OBJ 업로드였던 경우 채워집니다.
- Name
  stl
  Type
  string
  Description
  복구된 STL에 대한 다운로드 가능한 URL입니다. 입력이 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
thumbnail_url의 투명 배경(RGBA) 버전에 대한 다운로드 가능한 URL입니다. 작업이 alpha_thumbnail: true로 생성되고 투명 미리보기가 성공적으로 렌더링된 경우에만 존재하며, 그렇지 않으면 이 필드는 생략됩니다.
Name
texture_urls
Type
array
Description
항상 빈 배열입니다. 복구는 입력 지오메트리만 보존하며 텍스처를 다시 베이크하지 않습니다.
Name
consumed_credits
Type
integer
Description
이 작업에서 소비한 크레딧 수입니다. 작업이 SUCCEEDED에 도달하면 10입니다. FAILED 작업의 경우 0을 반환합니다(실패 시 크레딧이 환불됩니다).

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=***",
    "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
}