모델 형식 변환

POST /v3/models/convert

3D 모델을 다른 형식으로 변환합니다.

요청 매개변수

요청 헤더

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

요청 본문

기본 매개변수

매개변수	유형	필수	기본값	설명
input	문자열	예	-	모델 소스. `task_`로 시작하는 task_id 또는 `file_`로 시작하는 file_token를 허용합니다.
format	문자열	예	-	대상 형식. 사용 가능한 값: `GLTF`, `USDZ`, `FBX`, `OBJ`, `STL`, `3MF`. 3MF: 단색 3D.

메시 옵션

매개변수	유형	필수	기본값	설명
quad	부울	아니요	`false`	쿼드 리메싱
force_symmetry	부울	아니요	`false`	강제 대칭. `quad`가 `true`인 경우에만 유효합니다.
face_limit	정수	아니요	-	최대 폴리카운트. 생략하면 원래 면 수가 유지됩니다.
flatten_bottom	부울	아니요	`false`	바닥을 편평하게 하다
flatten_bottom_threshold	플로트	아니요	`0.01`	평탄화 깊이 임계값

텍스처 옵션

매개변수	유형	필수	기본값	설명
texture_size	정수	아니요	`4096`	확산 텍스처 크기(픽셀)
texture_format	문자열	아니요	`JPEG`	텍스처 형식. 사용 가능한 값: `BMP`, `DPX`, `HDR`, `JPEG`, `PNG`, `TARGA`, `TIFF`, `WEBP`
bake	부울	아니요	`true`	고급 재료를 기본 텍스처로 굽습니다.
pack_uv	부울	아니요	`false`	모든 UV를 통합 레이아웃으로 패키징
export_vertex_colors	부울	아니요	`false`	정점 색상을 포함합니다. `OBJ` 및 `GLTF` 형식에만 유효합니다.

내보내기 옵션

매개변수	유형	필수	기본값	설명
pivot_to_center_bottom	부울	아니요	`false`	피벗을 아래쪽 중앙으로 이동
scale_factor	플로트	아니요	`1`	스케일 팩터
with_animation	부울	아니요	`true`	뼈대 및 애니메이션 데이터 포함
animate_in_place	부울	아니요	`false`	내부 애니메이션
part_names	문자열[]	아니요	-	mesh/segment 데이터에서 내보낼 부품 이름
export_orientation	문자열	아니요	`+x`	수출 방향. 사용 가능한 값: `-x`, `-y`, `+y`
fbx_preset	문자열	아니요	`blender`	FBX는 호환성을 위해 사전 설정되어 있습니다. 사용 가능한 값: `blender`, `3dsmax`, `mixamo`, `bake_scale`

요청 예시

curl -X POST https://openapi.tripo3d.ai/v3/models/convert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "input": "task_abc123",
    "format": "FBX",
    "quad": true,
    "face_limit": 8000,
    "texture_size": 2048,
    "texture_format": "PNG",
    "pivot_to_center_bottom": true,
    "fbx_preset": "blender"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/models/convert"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "input": "task_abc123",
    "format": "FBX",
    "quad": True,
    "face_limit": 8000,
    "texture_size": 2048,
    "texture_format": "PNG",
    "pivot_to_center_bottom": True,
    "fbx_preset": "blender"
}

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

const url = "https://openapi.tripo3d.ai/v3/models/convert";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    input: "task_abc123",
    format: "FBX",
    quad: true,
    face_limit: 8000,
    texture_size: 2048,
    texture_format: "PNG",
    pivot_to_center_bottom: true,
    fbx_preset: "blender"
  })
});

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	2006	잘못된 입력 소스 작업 유형	`task_id`의 작업 유형이 올바른지 확인하세요.
400	2007	소스 작업이 성공적으로 완료되지 않았습니다.	변환을 시작하기 전에 소스 작업이 완료될 때까지 기다리세요.
403	2010	크레딧이 부족합니다.	크레딧을 충전하고 다시 시도하세요.