# 모델 가져오기
> **POST** `/v3/models/import`
외부 3D 모델 파일을 Tripo 플랫폼으로 가져옵니다.
> 표시된 작업 ID는 예시입니다. API에서 반환한 실제 ID로 바꾸세요.
## 요청 매개변수
### 요청 헤더
| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
| :-: | :-: | :-: | :-: | :-: |
| Content-Type | 문자열 | 예 | - | `application/json` |
| Authorization | 문자열 | 예 | - | `Bearer {api_key}` |
### 요청 본문
| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
| :-: | :-: | :-: | :-: | :-: |
| input | 문자열 | 예 | - | 모델 파일 소스. `file_`로 시작하는 file_token 또는 `http(s)://`로 시작하는 URL를 허용합니다. 지원되는 형식: GLB, GLTF, FBX, OBJ, STL, 최대 150개 MB |
## 요청 예시
### curl
```bash
curl -X POST https://openapi.tripo3d.ai/v3/models/import \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {api_key}" \
-d '{
"input": "file_abc123"
}'
```
### Python
```python
import requests
url = "https://openapi.tripo3d.ai/v3/models/import"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer {api_key}"
}
payload = {
"input": "file_abc123"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
### JavaScript
```javascript
const url = "https://openapi.tripo3d.ai/v3/models/import";
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer {api_key}"
},
body: JSON.stringify({
input: "file_abc123"
})
});
const data = await response.json();
console.log(data);
```
## 응답
### 성공적인 대응
```json
{
"code": 0,
"data": {
"task_id": "550e8400-e29b-41d4-a716-446655440001"
}
}
```
### 응답 필드
| 매개변수 | 유형 | 설명 |
| :-: | :-: | :-: |
| code | 정수 | 상태 코드. `0`는 성공을 나타냅니다. |
| data.task_id | 문자열 | 생성 진행 상황 및 결과를 쿼리하는 데 사용되는 고유 작업 식별자 |
### 작업 결과 필드
`status=success` 이후 `GET /v3/tasks/{task_id}`는 `data.output`에 다음 필드를 반환합니다:
| 매개변수 | 유형 | 설명 |
| :-: | :-: | :-: |
| model_url | string | 가져온 모델 다운로드 URL |
| rendered_image_url | string | 렌더링된 미리보기 이미지 URL |
| normalize_scale | number | 가져온 모델을 정규화할 때 적용된 균일 스케일 계수: `정규화 후 크기 = 정규화 전 크기 × normalize_scale`. `1.0`은 스케일이 적용되지 않았음을 의미하지만 이동은 발생했을 수 있습니다. 정규화 후 크기를 이 값으로 나누면 정규화 전 크기를 복원할 수 있으며, 플랫폼 출력은 정규화된 결과를 유지합니다. 모델 가져오기 작업 및 모델 입력이 `file_token` 또는 URL인 모델 후처리 작업(리깅, 텍스처, 변환 등, 먼저 모델을 가져옴)에서 반환되며, 입력이 `task_id`인 작업과 이 필드가 추가되기 전에 생성된 작업에는 반환되지 않습니다 |
| normalize_translation | number[] | 가져온 모델을 정규화할 때 적용된 이동 벡터로, 형식은 `[tx, ty, tz]`(숫자 3개)입니다. `normalize_scale`과 함께 사용합니다: `정규화 후 좌표 = 정규화 전 좌표 × normalize_scale + normalize_translation`; `정규화 전 좌표 = (정규화 후 좌표 - normalize_translation) / normalize_scale`. 가져오기 처리에서 이 값을 제공하는 경우에만 반환되며, 반환하는 작업은 `normalize_scale`과 같습니다. 입력이 `task_id`인 작업과 이 필드가 추가되기 전에 생성된 작업에는 반환되지 않습니다 |
## 오류 코드
| HTTP 상태 코드 | 오류 코드 | 설명 | 추천 |
| :-: | :-: | :-: | :-: |
| 429 | 2000 | 생성 한도를 초과했습니다. | 요청 속도를 줄이고 나중에 다시 시도하세요. |
| 400 | 1004 | 지원되지 않는 요청 매개변수 | 요청 본문 매개변수 이름 및 값 범위 확인 |
| 400 | 2006 | 잘못된 입력 소스 작업 유형 | 입력 파일 형식이 지원되는지 확인 |
| 400 | 2007 | 소스 작업이 성공적으로 완료되지 않았습니다. | 파일 업로드가 완료되었는지 확인 |
| 403 | 2010 | 크레딧이 부족합니다. | 크레딧을 충전하고 다시 시도하세요. |
모델 가져오기
POST/v3/models/import
외부 3D 모델 파일을 Tripo 플랫폼으로 가져옵니다.
표시된 작업 ID는 예시입니다. API에서 반환한 실제 ID로 바꾸세요.
요청 매개변수
요청 헤더
매개변수
유형
필수
기본값
설명
Content-Type
문자열
예
-
application/json
Authorization
문자열
예
-
Bearer {api_key}
요청 본문
매개변수
유형
필수
기본값
설명
input
문자열
예
-
모델 파일 소스. file_로 시작하는 file_token 또는 http(s)://로 시작하는 URL를 허용합니다. 지원되는 형식: GLB, GLTF, FBX, OBJ, STL, 최대 150개 MB
status=success 이후 GET /v3/tasks/{task_id}는 data.output에 다음 필드를 반환합니다:
매개변수
유형
설명
model_url
string
가져온 모델 다운로드 URL
rendered_image_url
string
렌더링된 미리보기 이미지 URL
normalize_scale
number
가져온 모델을 정규화할 때 적용된 균일 스케일 계수: 정규화 후 크기 = 정규화 전 크기 × normalize_scale. 1.0은 스케일이 적용되지 않았음을 의미하지만 이동은 발생했을 수 있습니다. 정규화 후 크기를 이 값으로 나누면 정규화 전 크기를 복원할 수 있으며, 플랫폼 출력은 정규화된 결과를 유지합니다. 모델 가져오기 작업 및 모델 입력이 file_token 또는 URL인 모델 후처리 작업(리깅, 텍스처, 변환 등, 먼저 모델을 가져옴)에서 반환되며, 입력이 task_id인 작업과 이 필드가 추가되기 전에 생성된 작업에는 반환되지 않습니다
normalize_translation
number[]
가져온 모델을 정규화할 때 적용된 이동 벡터로, 형식은 [tx, ty, tz](숫자 3개)입니다. normalize_scale과 함께 사용합니다: 정규화 후 좌표 = 정규화 전 좌표 × normalize_scale + normalize_translation; 정규화 전 좌표 = (정규화 후 좌표 - normalize_translation) / normalize_scale. 가져오기 처리에서 이 값을 제공하는 경우에만 반환되며, 반환하는 작업은 normalize_scale과 같습니다. 입력이 task_id인 작업과 이 필드가 추가되기 전에 생성된 작업에는 반환되지 않습니다