Auto Split API

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

분할 결과는 입력 텍스처를 유지하지 않습니다. Auto Split은 텍스처가 적용된 입력을 허용하므로, should_texture: false로 모델을 다시 생성할 필요가 없습니다. 분할된 부품을 재구성하고 각 부품에 단색 정점 색상을 지정합니다. 내보내는 형식에는 입력 텍스처 맵이 포함되지 않습니다.

POST/openapi/v1/print/split

Auto Split 작업 삭제

이 엔드포인트는 관련된 모든 모델과 데이터를 포함하여 Auto Split 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

Name
id
Type
path
Description
삭제할 Auto Split 작업의 ID입니다.

작업 상태

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

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

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

반환값

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

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/split/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/split

Auto Split 작업 목록 조회

이 엔드포인트를 사용하면 Auto Split 작업 목록을 조회할 수 있습니다.

매개변수

선택 속성

Name
page_num
Type
integer
Description
페이지네이션을 위한 페이지 번호입니다. 1부터 시작하며 기본값은 1입니다.
Name
page_size
Type
integer
Description
페이지 크기 제한입니다. 기본값은 10개 항목입니다. 최대 허용값은 100개 항목이며, 이를 초과하는 값은 100으로 조정됩니다.
Name
sort_by
Type
string
Description
정렬 기준 필드입니다. 사용 가능한 값:
- +created_at: 생성 시간 오름차순으로 정렬합니다.
- -created_at: 생성 시간 내림차순으로 정렬합니다.

반환 값

Auto Split 작업 객체의 페이지네이션된 목록을 반환합니다.

Request

GET

/openapi/v1/print/split

curl https://api.meshy.ai/openapi/v1/print/split?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/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
  }
]

GET/openapi/v1/print/split/:id/stream

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가 나타납니다. error 이벤트는 status_code와 message만 포함하므로, status를 읽기 전에 이벤트 이름에 따라 분기 처리해야 합니다.

Request

GET

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

curl -N https://api.meshy.ai/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.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/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
}

The Auto Split Task Object

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

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부사항으로 작업 id에 k-sortable UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
작업의 유형입니다. 값은 print-split입니다.
Name
model_urls
Type
object
Description
분할된 모델의 다운로드 가능한 URL로, 요청된 형식마다 하나씩 제공됩니다. 씬 객체를 지원하는 형식은 각 파트를 별도의 객체로 유지하며, stl은 이를 하나의 솔리드로 융합합니다. 요청하지 않은 형식의 속성은 생략됩니다.
- Name
  glb
  Type
  string
  Description
  GLB 형식으로 된 분할 모델의 다운로드 가능한 URL입니다.
- Name
  obj
  Type
  string
  Description
  OBJ 형식으로 된 분할 모델의 다운로드 가능한 URL입니다.
- Name
  fbx
  Type
  string
  Description
  FBX 형식으로 된 분할 모델의 다운로드 가능한 URL입니다.
- Name
  stl
  Type
  string
  Description
  STL 형식으로 된 분할 모델의 다운로드 가능한 URL입니다. 모든 파트가 하나의 솔리드로 융합됩니다. 개별적으로 선택 가능한 파트가 필요하면 3mf를 요청하세요.
- 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 작업이거나 prompt가 그대로 따라진 경우에는 생략됩니다.
Name
part_count
Type
integer
Description
분할 결과로 생성된 출력 가능한 파트의 수입니다. 씬 객체를 지원하는 형식은 파트마다 하나의 객체를 가지며, stl은 이를 하나의 솔리드로 융합하지만 개수는 여전히 파트 수를 기준으로 보고됩니다. 세그멘테이션이 출력 가능한 조각으로 만들지 못해 무너진 조각들은 내보내기 전에 파일에서 제거되며 개수에 포함되지 않습니다.
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 객체 참조는 오류를 참고하세요. 모델 제공업체의 안전 검사에서 입력 모델이 거부되면, 작업은 task_error.type invalid_input과 code provider_content_refused로 실패합니다. 오류를 참고하세요.
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.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/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

The Auto Split Task Object

The Auto Split Task Object