v2에서 v3로 마이그레이션 가이드
이 문서는 기존 코드를 Tripo API v2에서 v3로 마이그레이션하는 데 도움이 됩니다.
Skill로 V2에서 V3로 마이그레이션하기
API 차이를 처음부터 모두 이해할 필요는 없습니다. 이 Skill을 다운로드해 마이그레이션할 프로젝트 디렉터리에 넣은 다음, AI 코딩 도구에 이 파일을 사용하도록 지시하세요. 프로젝트의 V2 호출을 찾아 V3로 단계별로 마이그레이션할 수 있도록 도와줍니다.
1단계: Skill 다운로드
SKILL.md라는 이름의 파일을 받게 됩니다. 파일 이름을 바꾸지 마세요.
2단계: 프로젝트 디렉터리에 넣고 Skill 사용하기
다운로드한 SKILL.md를 마이그레이션할 프로젝트 디렉터리에 넣은 다음, 해당 프로젝트를 열고 AI에 이 Skill을 사용하라고 바로 지시하세요.
3단계: 이 프롬프트를 복사해 마이그레이션 시작하기
마이그레이션할 프로젝트를 여세요. 아래 프롬프트 전체를 복사해 Skills를 지원하는 AI 코딩 도구에 보내세요.
프로젝트 디렉터리의 `SKILL.md`를 사용하여 이 프로젝트의 Tripo API 연동을 V2에서 V3로 마이그레이션하세요. 먼저 변경해야 할 내용을 보여 주세요. 제 확인을 기다렸다가, 제가 확인하면 변경 사항을 적용하세요. 마지막으로 파일에 있는 체크리스트에 따라 누락된 변경 사항이 없는지 확인하세요.
도구가 먼저 V2 호출을 찾아 계획을 보여 주므로 모든 파일을 직접 검색할 필요가 없습니다.
주요 변경 사항
1. 베이스 URL 변경
# v2
https://api.tripo3d.ai/v2/openapi/
# v3
https://openapi.tripo3d.ai/v3/
2. 범용 엔드포인트를 전용 엔드포인트로 분할
v2는 단일 POST /v2/openapi/task 엔드포인트와 type 필드를 사용하여 작업 유형을 구별합니다. v3는 각 기능에 대한 전용 엔드포인트를 제공하므로 type 필드는 더 이상 필요하지 않습니다.
JSON
// v2
POST /v2/openapi/task
{ "type": "text_to_model", "prompt": "a cat" }
// v3
POST /v3/generation/text-to-model
{ "prompt": "a cat" }
3. input 필드로 통합된 파일 입력
v2에서는 file, file_token, url, object 등 입력 소스에 따라 다른 필드 이름이 사용됩니다. v3에서는 input 필드 아래로 통합되며 시스템이 자동으로 입력 유형을 추론합니다.
JSON
// v2 - different field names are required
{ "type": "refine_model", "draft_model_task_id": "task_abc123" }
{ "type": "convert_model", "original_model_task_id": "task_abc123" }
// v3 - use input consistently
{ "input": "task_abc123" }
{ "input": "https://example.com/model.glb" }
{ "input": "file_token_abc123" }
4. 표준화된 필드 이름
| v2 필드 | v3 필드 |
|---|---|
create_time |
created_at |
consumed_credit |
credits_consumed |
5. 텍스트-이미지 및 이미지-이미지 분할
v2에서 텍스트-이미지 및 이미지-이미지는 동일한 API를 공유합니다. v3에서는 전용 엔드포인트로 분할됩니다.
POST /v3/generation/text-to-image- 텍스트 전용 입력에서 이미지 생성POST /v3/generation/image-to-image- 참조 이미지를 기반으로 이미지 생성 또는 편집
끝점 매핑
세대
| v2 유형 값 | v3 엔드포인트 |
|---|---|
text_to_model |
POST /v3/generation/text-to-model |
image_to_model |
POST /v3/generation/image-to-model |
multiview_to_model |
POST /v3/generation/multiview-to-model |
text_to_image |
POST /v3/generation/text-to-image |
generate_image |
POST /v3/generation/image-to-image |
generate_multiview_image |
POST /v3/generation/image-to-multiview |
edit_multiview_image |
POST /v3/generation/edit-multiview |
모델 처리
| v2 유형 값 | v3 엔드포인트 |
|---|---|
refine_model |
POST /v3/models/refine |
convert_model |
POST /v3/models/convert |
import_model |
POST /v3/models/import |
stylize_model |
POST /v3/models/stylize |
texture_model |
POST /v3/models/texture |
애니메이션
| v2 유형 값 | v3 엔드포인트 |
|---|---|
animate_prerigcheck |
POST /v3/animations/rig-check |
animate_rig |
POST /v3/animations/rig |
animate_retarget |
POST /v3/animations/retarget |
메시 편집
| v2 유형 값 | v3 엔드포인트 |
|---|---|
mesh_segmentation |
POST /v3/mesh/segment |
mesh_completion |
POST /v3/mesh/complete |
highpoly_to_lowpoly |
POST /v3/mesh/decimate |
작업 및 파일
| v2 엔드포인트 | v3 엔드포인트 |
|---|---|
GET /v2/openapi/task/{task_id} |
GET /v3/tasks/{task_id} |
POST /v2/openapi/upload |
POST /v3/files |
마이그레이션 단계
1단계: 기본 URL 업데이트
Python
# v2
BASE_URL = "https://api.tripo3d.ai/v2/openapi"
# v3
BASE_URL = "https://openapi.tripo3d.ai/v3"
2단계: 매핑 테이블을 사용하여 끝점 교체
Python
# v2
response = requests.post(f"{BASE_URL}/task", json={
"type": "text_to_model",
"prompt": "a cat"
})
# v3
response = requests.post(f"{BASE_URL}/generation/text-to-model", json={
"prompt": "a cat"
})
3단계: type 필드 제거
v3에서 엔드포인트 경로는 이미 작업 유형을 암시하므로 요청 본문에는 더 이상 type 필드가 필요하지 않습니다.
4단계: 입력 필드를 input로 바꾸기
Python
# v2 - different task types use different field names
payload = {"type": "refine_model", "draft_model_task_id": "task_abc123"}
payload = {"type": "convert_model", "original_model_task_id": "task_abc123"}
# v3 - use input consistently
payload = {"input": "task_abc123"}
5단계: 응답 필드 이름 업데이트
Python
# v2
created = task["create_time"]
cost = task["consumed_credit"]
# v3
created = task["created_at"]
cost = task["credits_consumed"]
6단계: 테스트 및 검증
- 각 엔드포인트를 한 번에 하나씩 교체 및 테스트
- 작업 생성 및 폴링이 올바르게 작동하는지 확인
- 다운로드 링크를 사용할 수 있는지 확인
- 신용 공제 및 잔액 조회가 올바르게 작동하는지 확인하세요.
메모
- v2 및 v3는 병렬로 실행될 수 있습니다. 한꺼번에 전환하는 대신 점진적으로 마이그레이션하는 것이 좋습니다.
- API Keys는 v2와 v3 간에 공유됩니다. 새 키를 만들 필요가 없습니다.
- 작업 ID 형식은 변경되지 않습니다. v2에서 생성된 작업은 v3에서 쿼리할 수 있습니다.