프린팅 가능성 복구 API

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

POST/openapi/v1/print/repair

Create a Repair Printability Task

이 엔드포인트는 새로운 프린팅 가능성 복구 작업을 생성합니다. 이 작업은 3D 모델에 대해 topology 복구를 실행하고 워터타이트(watertight)하고 출력 가능한 상태의 버전을 반환합니다.

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

Parameters

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

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

  • Name
    model_url
    Type
    string
    필수
    Description

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

  • Name
    alpha_thumbnail
    Type
    boolean
    기본값 false
    Description

    true로 설정하면, 작업이 추가로 투명 배경(RGBA) 버전의 미리보기를 렌더링하여 GET 응답에서 alpha_thumbnail_url로 반환합니다. 기존 thumbnail_url 필드는 변경되지 않습니다.

Returns

응답의 result 속성에는 새로 생성된 프린팅 가능성 복구 작업의 id가 포함됩니다.

Failure Modes

  • Name
    400 - Bad Request
    Description

    요청을 수락할 수 없습니다. 일반적인 원인:

    • 누락된 파라미터: input_task_id와 model_url 모두 제공되지 않았습니다.
    • 잘못된 UUID: input_task_id가 유효한 UUID가 아닙니다.
    • 잘못된 모델 URL: model_url의 형식이 잘못되었거나, 지원되지 않는 스킴을 사용하거나, 지원되지 않는 파일 확장자를 사용합니다.
    • 모델 파일이 너무 큼: model_url의 본문이 100MB를 초과했습니다.
    • 작업 미완료: 참조된 작업이 아직 대기 중이거나, 진행 중이거나, 실패했습니다.
    • 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입니다.

반환값

프린팅 가능성 복구 작업 객체입니다. model_urls 블록은 작업이 SUCCEEDED 상태에 도달할 때까지 비어 있습니다. 입력 형식과 일치하는 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": "",
    "gltf": "",
    "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입니다.

작업 상태

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

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

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

반환값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS 상태인 경우 409 Conflict를 반환합니다.

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

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

프린팅 가능성 복구 작업 목록 조회

이 엔드포인트를 사용하면 프린팅 가능성 복구 작업 목록을 조회할 수 있습니다.

매개변수

선택 속성

  • 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: 생성 시간 내림차순으로 정렬합니다.

반환값

프린팅 가능성 복구 작업 객체의 페이지네이션된 목록을 반환합니다.

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=***",
      "gltf": "",
      "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 형태로 프린팅 가능성 복구 작업 객체의 스트림을 반환합니다.

모든 프레임은 해당 단계의 전체 작업 객체를 담고 있으며 — Get 엔드포인트가 반환하는 것과 동일한 형태입니다 — 따라서 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 출력 필드가 아직 채워지지 않았을 뿐이고(null, [] 또는 {}), finished_at은 null입니다. 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.
// 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-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=***",
    "gltf": "",
    "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
}

The Repair Printability Task Object

  • 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

    태스크의 진행 상황입니다. 태스크가 아직 시작되지 않았다면 이 속성은 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
      gltf
      Type
      string
      Description

      복구된 GLTF를 다운로드할 수 있는 URL입니다. 입력이 GLTF 업로드인 경우 채워집니다.

    • Name
      fbx
      Type
      string
      Description

      복구된 FBX를 다운로드할 수 있는 URL입니다. 입력이 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=***",
    "gltf": "",
    "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
}