스마트 세분화

POST /v3/mesh/smartsegment

엔드투엔드 스마트 세분화 파이프라인. file_token 또는 공개 URL를 통해 제출하세요. 이미지 및 모델 경로를 모두 지원합니다. 이미지 파이프라인 자동 모델 이후 세그먼트(85크레딧); 모델 파이프라인은 기존 GLB(55크레딧)를 분할합니다.

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

요청 매개변수

요청 헤더

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

요청 본문

매개변수	유형	필수	기본값	설명
seg_type	문자열	예	—	분할 유형: `image`(이미지 파이프라인, 85크레딧) / `model`(모델 파이프라인, 55크레딧)
input	문자열	예	—	입력 소스: `file_token`(`/v3/files` 또는 `/v3/files/presign`에서) 또는 공개 URL
granularity	문자열	아니요	`medium`	분할 세분성: `coarse` / `medium` / `fine`
hint	문자열	아니요	—	분할할 부품을 식별하는 데 도움이 되는 선택적 힌트
transform	번호[]	조건부	—	`seg_type=model`인 경우 필수. 열 주요 4×4 변환 행렬(16개 부동 소수점)

seg_type 및 형식 제약 조건

seg_type	입력	형식	추가 필요	크레딧	응답 유형
`image`	이미지 file_token 또는 URL	PNG / JPEG / 웹P	없음	85	`smartsegment_image`
`model`	3D 모델 file_token 또는 URL	GLB만 해당	`transform`	55	`smartsegment_model`

seg_type=model 형식 제한: 모델 입력은 GLB(이진 glTF)여야 합니다. GLB가 아닌 파일은 매개변수 오류를 반환합니다.

transform는 열 주요 4×4 행렬입니다. 공통 단위 행렬:

JSON

[1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]

요청 예시

curl — 이미지 (file_token)

Bash

curl -X POST https://openapi.tripo3d.ai/v3/mesh/smartsegment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "seg_type": "image",
    "input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "granularity": "medium",
    "hint": "game character with sword and armor"
  }'

curl — 모델(URL + 변환)

Bash

curl -X POST https://openapi.tripo3d.ai/v3/mesh/smartsegment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "seg_type": "model",
    "input": "https://example.com/character.glb",
    "transform": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
    "granularity": "fine",
    "hint": "character body parts"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/mesh/smartsegment"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "seg_type": "image",
    "input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "granularity": "medium"
}

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

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

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    seg_type: "image",
    input: "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    granularity: "medium"
  })
});

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

응답

성공을 창조하다

JSON

{
  "code": 0,
  "data": {
    "task_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "type": "smartsegment_image",
    "status": "queued"
  }
}

작업 결과(성공)

표준 API GET /v3/tasks/{task_id}를 사용하여 폴링합니다.

JSON

{
  "code": 0,
  "data": {
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "smartsegment_image",
    "status": "success",
    "progress": 100,
    "input": {
      "granularity": "medium"
    },
    "output": {
      "prompt": "head, body, left arm, right arm, legs",
      "mask_url": "https://cdn.tripo3d.ai/.../mask.png?auth_key=...",
      "seg_model_url": "https://cdn.tripo3d.ai/.../model.glb?auth_key=...",
      "seg_task_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "model_task_id": "d4e5f6a7-b8c9-0123-defa-456789012345"
    },
    "credits_consumed": 85.00,
    "created_at": "2026-06-30T09:08:14.882623Z",
    "completed_at": "2026-06-30T09:14:15.183547Z"
  }
}

응답 필드

매개변수	유형	설명
code	정수	상태 코드. `0`는 성공을 나타냅니다.
data.task_id	문자열	진행 상황과 결과를 폴링하는 데 사용되는 고유 작업 ID
data.output.prompt	문자열	자동 생성되는 쉼표 구분 영어 라벨
data.output.mask_url	문자열	CDN-는 PNG 시맨틱 마스크의 URL로 서명되었습니다.
data.output.seg_model_url	문자열	분할된 GLB 모델의 CDN-서명된 URL
data.output.seg_task_id	문자열	내부 mesh_segmentation 하위 작업 ID
data.output.model_task_id	문자열	내부 image_to_model / import_model 하위 작업 ID

오류 코드

HTTP 상태 코드	오류 코드	설명	추천
429	2000	세대 동시성 한도를 초과했습니다.	요청 비율을 줄이고 나중에 다시 시도하세요.
400	1004	잘못된 매개변수 오류(잘못된 형식, GLB가 아님, 변환 누락 등)	`seg_type` / `input` / `transform` 확인
402	2001	크레딧이 부족합니다.	크레딧을 충전하고 다시 시도하세요.
401	4000	인증 실패	API Key 확인