멀티뷰에서 3D 모델로

POST /v3/generation/multiview-to-model

다중 뷰 이미지에서 3D 모델을 생성합니다.

요청 매개변수

요청 헤더

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

매개변수	유형	필수	기본값	설명
inputs	객체[] \	문자열[4]	예	-
model	문자열	아니요	`tripo-v3.1`	AI 모델 버전. 지원되는 값: `tripo-p1`, `tripo-turbo`, `tripo-v3.1`, `tripo-v3.0`, `tripo-v2.5`, `tripo-v2.0`
face_limit	정수	아니요	적응형	출력의 최대 폴리카운트
texture	부울	아니요	`true`	텍스처 맵 활성화
pbr	부울	아니요	`true`	PBR 재료를 활성화합니다. 활성화되면 `texture`가 강제로 `true`로 전환됩니다.
texture_seed	정수	아니요	무작위	텍스처 생성을 위한 무작위 시드
texture_quality	문자열	아니요	`standard`	텍스처 품질. 지원되는 값: `fast`(`texture_version=v3.5-20260815` 필요), `standard`, `detailed`, `extreme`
texture_version	문자열	아니요	model에서 파생	지오메트리와 독립적으로 텍스처 모델을 지정합니다. 지원되는 값: `v3.5-20260815`, `v3.0-20250812`, `v2.5-20250123`. 생략하면 지오메트리 `model`에서 파생됩니다(v2.5 지오메트리 → `v2.5-20250123`, 그 외 → `v3.0-20250812`).
delight	부울	아니요	`true`	텍스처링 전에 참조 이미지에서 구워진 조명을 제거합니다. `texture_version=v3.5-20260815`인 경우에만 적용됩니다.
geometry_quality	문자열	아니요	`standard`	기하학 품질. `standard`(밸런스), `detailed`(울트라 모드)
auto_size	부울	아니요	`false`	모델을 실제 크기(미터)에 맞게 자동으로 확장
quad	부울	아니요	`false`	쿼드 메시를 출력합니다. 활성화되면 출력 형식이 FBX로 강제 설정됩니다.
smart_low_poly	부울	아니요	`false`	손으로 만든 토폴로지 스타일로 로우 폴리 모델 생성
generate_parts	부울	아니요	`false`	편집 가능한 분할된 부품을 생성합니다. `texture`, `pbr`, `quad`, `smart_low_poly`와 호환되지 않음 — 아래 참고 사항 참조
compress	문자열	아니요	-	압축 유형. `geometry`(meshopt 압축)
export_orientation	문자열	아니요	`+x`	수출 방향. 사용 가능한 값: `-x`, `-y`, `+y`

generate_parts 참고 사항:

texture, pbr, quad, smart_low_poly와 호환되지 않습니다:

texture=true 또는 pbr=true — texture를 생략하는 경우(기본값 true)를 포함 — 요청이 오류 코드 1004로 거부됩니다.
quad=true — quad는 무시되며 반환되는 부품은 삼각형 메시입니다.
smart_low_poly=true — smart_low_poly가 우선 적용되며 부품이 생성되지 않습니다.

부품을 생성하려면 texture=false와 pbr=false를 설정하고 quad와 smart_low_poly를 보내지 마세요.

export_orientation 참고 사항:

이번 생성에만 적용됩니다. 모델을 후처리 작업(텍스처, 리그, 리타겟, 변환 등)에 사용할 경우 이 파라미터를 설정하지 않는 것이 좋습니다.
설정하면 후처리 시 모델 방향 오류로 인해 최종 결과에 영향을 줄 수 있지만, 작업은 계속 status: success를 보고합니다 — 오류가 발생하지 않습니다. 주의해서 사용하세요.
모델을 후처리할 계획이라면 이 파라미터를 설정하지 말고 마지막 단계에서 /v3/models/convert를 사용하여 방향을 변환하세요.

다음 매개변수는 model >= tripo-v3.0인 경우에만 유효합니다: texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

입력 형식

보기 키(권장)

각 배열 요소는 front, left, back 또는 right 중 정확히 하나의 키를 가진 객체입니다. 순서는 중요하지 않습니다. 서버는 [front, left, back, right]로 표준화됩니다. front가 필요합니다. 최소한 두 개의 뷰가 비어 있지 않아야 합니다.

URL 사용 시:

JSON

{
  "inputs": [
    {"front": "https://example.com/front.png"},
    {"back": "https://example.com/back.png"},
    {"right": "https://example.com/right.png"}
  ],
  "model": "tripo-v3.1",
  "texture": false,
  "geometry_quality": "detailed"
}

file_tokens 사용(업로드 파일 API를 통해 획득):

JSON

{
  "inputs": [
    {"front": "3154b4b0-4647-4032-aa82-827441ae92ef"},
    {"back": "58ea3eab-6a08-4deb-98f9-e60f1802954d"},
    {"right": "584b0e07-8576-4eb4-bf49-2e149e0252f6"}
  ],
  "model": "tripo-v3.1",
  "texture": false,
  "geometry_quality": "detailed"
}

레거시 위치

[front, left, back, right] 순서로 정확히 4개의 문자열입니다. 보기를 건너뛰려면 빈 문자열 ""를 사용하세요.

JSON

{
  "inputs": [
    "file_front_token",
    "",
    "https://example.com/back.png",
    "https://example.com/right.png"
  ]
}

task_id(다중 뷰 작업 재사용)

이전 generate_multiview_image 또는 edit_multiview_image 작업의 ID를 전달하여 3D 생성을 위한 4뷰 출력을 재사용합니다. inputs는 하나의 task_id 개체가 있는 단일 요소 배열이어야 합니다. 뷰 키 또는 위치 슬롯과 혼합하지 마십시오. 소스 작업은 success 상태여야 합니다.

JSON

{
  "inputs": [
    {"task_id": "550e8400-e29b-41d4-a716-446655440000"}
  ],
  "model": "v3.1-20260211",
  "texture": true,
  "pbr": true
}

요청 예시

curl -X POST https://openapi.tripo3d.ai/v3/generation/multiview-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "inputs": [
      "https://example.com/front.png",
      "https://example.com/back.png",
      "https://example.com/left.png",
      "https://example.com/right.png"
    ],
    "model": "tripo-v3.1",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/multiview-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "inputs": [
        "https://example.com/front.png",
        "https://example.com/back.png",
        "https://example.com/left.png",
        "https://example.com/right.png"
    ],
    "model": "tripo-v3.1",
    "texture": True,
    "pbr": True,
    "texture_quality": "detailed"
}

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

const url = "https://openapi.tripo3d.ai/v3/generation/multiview-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    inputs: [
      "https://example.com/front.png",
      "https://example.com/back.png",
      "https://example.com/left.png",
      "https://example.com/right.png"
    ],
    model: "tripo-v3.1",
    texture: true,
    pbr: true,
    texture_quality: "detailed"
  })
});

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

응답

성공반응

JSON

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

응답 필드

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

오류 코드

HTTP 상태 코드	오류 코드	설명	추천
429	2000	생성 한도를 초과했습니다.	요청 빈도를 줄이고 나중에 다시 시도하세요.
400	2002	지원되지 않는 요청 매개변수	요청 본문 매개변수 이름 및 값 범위 확인
400	2003	입력 파일이 비어 있습니다.	업로드된 파일이 비어 있지 않은지 또는 URL에 액세스할 수 있는지 확인하세요.
400	2004	지원되지 않는 파일 형식	지원되는 이미지 형식(PNG, JPEG, WebP)을 사용하세요.
400	2008	입력 내용이 콘텐츠 정책을 위반합니다.	입력 이미지 교체 및 정책 위반 콘텐츠 제거
403	2010	크레딧이 부족합니다.	크레딧을 추가하고 다시 시도하세요.
400	2015	모델 버전이 지원 중단됨	`model`를 현재 지원되는 버전으로 업그레이드하세요.
400	2018	모델이 너무 복잡해서 다시 메시할 수 없습니다.	`face_limit`를 낮추거나 입력을 단순화하세요.