메시 의미론적 분할

POST /v3/mesh/segment

3D 모델에서 의미론적 분할을 수행하고 모델을 의미론적 부분으로 자동 분할합니다. v1(기하학 기반, 기본값) 및 v2(의미적 라벨링 + 기하학, 베타)를 지원합니다.

/v3/mesh/smartsegment와의 차이점: 이 API는 기존 모델만 분할합니다. SmartSegment는 엔드투엔드 파이프라인(자산 → 자동 모델링 → 세분화)입니다.

요청 매개변수

요청 헤더

매개변수	유형	필수	기본값	설명
Content-Type	문자열	예	—	`application/json`
Authorization	문자열	예	—	`Bearer {api_key}`

요청 본문

매개변수	유형	필수	기본값	설명
input	문자열	예	—	모델 소스. task_id, file_token 또는 URL 허용
model	문자열	아니요	`v1.0-20250506`	버전: `v1.0-20250506`(기본값) / `v2.0-20260430`(베타)
segmentation_granularity	문자열	아니요	`balanced`	v2만 해당. 세분성: `simple` / `balanced` / `detailed`
split_by_connectivity	부울	아니요	`true`	v2만 해당. 연결된 구성요소별로 분할할지 여부
ref_image	문자열	아니요	—	v2만 해당. 참조 이미지: `file_token` 또는 URL. `ref_image`가 제공되면 `segmentation_granularity` 및 `split_by_connectivity`는 무시됩니다

v1 대 v2

차원	v1 (`v1.0-20250506`)	v2(`v2.0-20260430`, 베타)
방법	기하학 / 토폴로지	의미론적 라벨링 + 기하학
`segmentation_granularity`	지원되지 않음	`simple` / `balanced` / `detailed`
`split_by_connectivity`	지원되지 않음	지원됨, 기본 `true`
`ref_image`	지원되지 않음(설정하면 오류 발생)	옵션 `file_token` 또는 URL

요청 예시

curl — v1(기본값)

Bash

-cmd">curl -X POST https://openapi.tripo3d.ai/v3/mesh/segment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "input": "task_abc123"}'

curl — v2(세분성 모드)

Bash

-cmd">curl -X POST https://openapi.tripo3d.ai/v3/mesh/segment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "model": "v2.0-20260430",
    "input": "task_abc123",
    "segmentation_granularity": "balanced",
    "split_by_connectivity": true
  }'

curl — v2 (ref_image 모드, 세분성 및 split_by_connectivity 무시)

Bash

-cmd">curl -X POST https://openapi.tripo3d.ai/v3/mesh/segment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "model": "v2.0-20260430",
    "input": "task_abc123",
    "ref_image": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

import requests

url = "https://openapi.tripo3d.ai/v3/mesh/segment"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "model": "v2.0-20260430",
    "input": "task_abc123",
    "ref_image": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const url = "https://openapi.tripo3d.ai/v3/mesh/segment";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    model: "v2.0-20260430",
    input: "task_abc123",
    ref_image: "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  })
});

const data = await response.json();
console.log(data);

응답

성공적인 대응

JSON

{
  "code": 0,
  "data": {
    "task_id": "task_def456"}
}

응답 필드

매개변수	유형	설명
code	정수	상태 코드. `0`는 성공을 나타냅니다.
data.task_id	문자열	분할 진행 상황 및 결과를 폴링하는 데 사용되는 고유 작업 식별자

오류 코드

HTTP 상태 코드	오류 코드	설명	추천
429	2000	생성 한도를 초과했습니다.	요청 속도를 줄이고 나중에 다시 시도하세요.
400	2002	지원되지 않는 요청 매개변수	요청 본문 매개변수 이름 및 값 범위 확인
400	1004	잘못된 매개변수(예: v1의 ref_image)	모델 버전 및 매개변수 조합 확인
400	2006	잘못된 입력 소스 작업 유형	task_id가 3D 모델 작업에 해당하는지 확인
400	2007	소스 작업 상태가 성공하지 못했습니다.	분할을 시작하기 전에 소스 작업이 완료될 때까지 기다리세요.
403	2010	크레딧이 부족합니다.	크레딧을 충전하고 다시 시도하세요.