Auto Split API

3D 모델을 별도로 출력 가능한 파트로 분할합니다 — 자동으로, 사용자가 지정한 부위별로, 또는 색상 영역별로 분할할 수 있으며 커넥터를 선택적으로 추가할 수 있습니다. 절단으로 인해 얇아진 부위는 항상 보강되어 모든 파트가 견고하게 출력됩니다.

Auto Split은 현재 텍스처가 없는 모델만 지원합니다. 이미지로 3D 및 멀티 이미지로 3D의 경우, should_texture를 false로 설정하여 입력을 생성하세요. 텍스처가 적용된 입력은 400으로 거부됩니다.

POST/openapi/v1/print/split

Auto Split 작업 스트리밍

이 엔드포인트는 Server-Sent Events(SSE)를 사용하여 Auto Split 작업의 실시간 업데이트를 스트리밍합니다.

매개변수

Name
id
Type
path
Description
스트리밍할 Auto Split 작업의 고유 식별자입니다.

반환값

Auto Split 작업 객체의 스트림을 Server-Sent Events로 반환합니다.

모든 message 이벤트는 Auto Split 작업 조회에서 반환되는 것과 동일한 전체 작업 객체를 담고 있으며, 여기에는 consumed_credits, 타임스탬프, prompt_ignored가 포함됩니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안 프레임마다 변경되는 필드는 progress, status, started_at, preceding_tasks이며, SUCCEEDED 상태에 도달하면 model_urls, thumbnail_url, part_count, parts가 나타납니다. error 이벤트는 status_code와 message만을 담고 있으므로, status를 읽기 전에 이벤트 이름으로 분기 처리해야 합니다.

Request

GET

/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.cn/openapi/v1/print/split/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Auto Split 작업 객체

Auto Split 작업은 아래 속성만 포함합니다. 다른 작업 객체에 포함되는 생성 프롬프트 필드(name, object_prompt, texture_prompt 등), 단일 model_url, 그리고 texture_urls는 분할 작업에서는 절대 채워지지 않으며 반환되지도 않습니다. 작업이 진행되는 동안 채워지는 속성(thumbnail_url, model_urls, 타임스탬프)은 값이 채워질 때까지 비어 있는 상태로 항상 존재하므로, PENDING과 SUCCEEDED 사이에서 키의 집합이 변하지 않습니다.

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현상 세부 사항으로 작업 id에는 k-정렬 가능한(k-sortable) UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 하지 말아야 합니다.
Name
type
Type
string
Description
작업의 유형입니다. 값은 print-split입니다.
Name
model_urls
Type
object
Description
분할된 모델을 다운로드할 수 있는 URL로, 요청한 형식마다 하나씩 제공됩니다. 각 파트는 파일 내에서 별도의 객체로 존재합니다. 요청하지 않은 형식에 대한 속성은 생략됩니다.
- Name
  glb
  Type
  string
  Description
  GLB 형식의 분할된 모델을 다운로드할 수 있는 URL입니다.
- Name
  obj
  Type
  string
  Description
  OBJ 형식의 분할된 모델을 다운로드할 수 있는 URL입니다.
- Name
  fbx
  Type
  string
  Description
  FBX 형식의 분할된 모델을 다운로드할 수 있는 URL입니다.
- Name
  usdz
  Type
  string
  Description
  USDZ 형식의 분할된 모델을 다운로드할 수 있는 URL입니다.
- Name
  blend
  Type
  string
  Description
  Blender 형식의 분할된 모델을 다운로드할 수 있는 URL입니다.
- Name
  3mf
  Type
  string
  Description
  3MF 형식의 분할된 모델을 다운로드할 수 있는 URL입니다.
Name
thumbnail_url
Type
string
Description
요청한 layout에 따라 각 파트가 서로 다른 색상으로 표시된, 분할된 모델의 렌더링 미리보기를 다운로드할 수 있는 URL입니다.
Name
prompt_ignored
Type
boolean
Description
by_parts 또는 by_color 요청의 prompt에 파트 이름이 지정되지 않아 Meshy가 대신 모델을 자동으로 분할한 경우 true가 됩니다 — 이 경우 결과에 표시되는 파트 이름은 사용자가 지정한 것이 아니라 Meshy가 지정한 이름입니다. PENDING 상태부터 존재합니다. auto 작업의 경우와 프롬프트가 그대로 따라진 경우에는 생략됩니다.
Name
part_count
Type
integer
Description
분할된 모델에서 인쇄 가능한 파트의 수로, 내보낸 파일 내의 객체마다 하나씩입니다. 세그멘테이션 과정에서 인쇄 가능한 조각으로 만들 수 없었던 붕괴된 조각들은 내보내기 전에 파일에서 제거되며 개수에 포함되지 않습니다.
Name
progress
Type
integer
Description
작업의 progress입니다. 작업이 아직 시작되지 않았다면 이 속성은 0입니다. 작업이 성공하면 100이 됩니다.
Name
status
Type
string
Description
작업의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
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
task_error
Type
object
Description
실패한 작업에 대한 오류 세부 정보입니다. task_error 객체의 전체 참조는 오류를 확인하세요.
Name
consumed_credits
Type
integer
Description
이 작업으로 소비된 크레딧 수입니다. 항상 존재하며, 작업이 접수되면 10이고, FAILED 작업의 경우 실패 시 요금이 환불되므로 0입니다. 작업이 여전히 PENDING 상태일 때 삭제해도 환불됩니다.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Auto Split API

Auto Split 작업 생성

매개변수

반환 값

실패 모드

Request

Response

Auto Split 작업 조회

매개변수

반환값

Request

Response

Auto Split 작업 삭제하기

경로 매개변수

반환값

Request

Response

Auto Split 작업 목록 조회

매개변수

선택적 속성

반환 값

Request

Response

Auto Split 작업 스트리밍

매개변수

반환값

Request

Response Stream

Auto Split 작업 객체

The Auto Split Task Object