Tripo3D

Tripo CLI: AI로 텍스트와 이미지를 3D 모델로 만들기

Tripo CLI: AI로 텍스트와 이미지를 3D 모델로 만들기

Tripo CLI는 AI 에이전트를 위해 설계되어 3D 제작을 채팅처럼 간단하게 만들어 줍니다. Codex, Claude Code, Cursor 같은 AI 코딩 도구 안에서든 CLI를 직접 사용하든, 자연어 설명 한 문장, 이미지 한 장 또는 기존 모델 하나만 있으면 3D 모델, 애니메이션 등 다양한 에셋을 생성하거나 변환할 수 있습니다. 전체 과정은 CLI가 자동으로 처리하므로 API나 모델 버전, 복잡한 매개변수를 이해할 필요가 없습니다.

CLI와 API 중 무엇을 써야 하나요?

Tripo는 두 가지 형태로 제공됩니다. 10초만 들여 나에게 맞는 것을 골라 보세요.

제품 이런 경우에 적합 시작하기
Tripo CLI(이 페이지) 입문자가 주요 Vibe Coding 도구로 AI 3D 기능을 빠르게 활용하고 싶을 때 계속 읽어 주세요
Tripo API 전문 개발자가 AI 3D 기능을 웹사이트, 앱 또는 자체 비즈니스 시스템에 통합할 때 빠른 시작

아직 잘 모르겠나요? 우선 이 페이지부터 따라 해 보세요. 설치는 무료이고, 크레딧은 실제로 모델을 생성할 때만 사용됩니다.

설치 및 로그인(두 경로 중 하나 선택)

아래 두 가지 설치 경로 중 하나를 선택하세요.

경로 1: AI에게 설치 맡기기(권장)

Cursor, Claude Code, Codex처럼 터미널 명령을 실행할 수 있는 AI 어시스턴트를 이미 사용한다면 이 방법이 가장 쉽습니다. 아래 프롬프트를 복사해 어시스턴트에게 그대로 보내세요.

Tripo CLI를 설정하고 각 단계를 설명해 주세요. Node.js 20 이상이 설치되어 있는지 확인하고 npm install -g tripo-cli를 실행해 주세요. 그런 다음 브라우저에서 tripo login을 완료하도록 안내하되 API 키를 채팅에 붙여 넣으라고 하지 마세요. 마지막으로 tripo doctor를 실행하고 인증, 네트워크, 잔액 검사가 통과했는지 알려 주세요.

이후 과정은 다음과 같습니다.

  1. AI가 컴퓨터 환경을 확인하고, Node.js가 없으면 먼저 설치를 도와줍니다.
  2. AI가 설치 명령을 실행합니다.
  3. 이제 여러분 차례입니다. 브라우저에 Tripo 로그인 페이지가 열리면 로그인한 뒤, 터미널에 표시된 인증 코드와 일치하는지 확인하고 승인하세요(이 단계는 반드시 본인이 직접 해야 하며, 어떤 키도 AI에게 보내면 안 됩니다).
  4. AI가 tripo doctor를 실행합니다. 모든 검사를 통과하면 설정 완료입니다.

그런 다음 바로 다음 섹션인 "첫 3D 모델 만들기"로 넘어가면 됩니다.

문제가 있나요? AI가 막히거나 오류가 발생한 경우
  • 터미널 오류를 그대로 AI에게 붙여 넣고 계속 진행하게 하세요. 대부분의 문제는 AI가 해결할 수 있습니다.
  • 로그인이 완료되지 않은 경우: 로그인 페이지를 다시 열고, 터미널에 표시된 인증 코드를 다시 확인한 뒤 승인하세요.
  • 그래도 안 되면 아래의 "경로 2: 직접 설치하기"를 따라 하세요. 명령 세 개면 충분합니다.

경로 2: 직접 설치하기

AI 어시스턴트가 없어도 괜찮습니다. 전체 과정은 명령 세 개가 전부입니다.

1단계: Tripo CLI 설치

다음 명령은 컴퓨터에 tripo 명령을 설치합니다.

Bash
npm install -g tripo-cli

정상이라면 빨간 오류 문구 없이 진행이 끝나며, 이는 설치가 성공했다는 뜻입니다.

문제가 있나요? npm을 찾을 수 없거나 권한 오류가 발생한 경우
  • npm을 찾을 수 없음: 아직 Node.js가 설치되지 않은 상태입니다. Node.js 웹사이트에서 현재 LTS 버전(20 이상)을 설치한 뒤 터미널을 다시 열고 다시 시도하세요.
  • macOS 권한 오류(EACCES): 대신 sudo npm install -g tripo-cli를 실행하고, 요청하면 컴퓨터 비밀번호를 입력하세요.
  • Windows에서 "스크립트를 실행할 수 없습니다"라고 나오는 경우: PowerShell을 관리자 권한으로 다시 열고 다시 시도하세요.

2단계: Tripo 계정에 로그인

Bash
tripo login

브라우저가 자동으로 인증 페이지를 엽니다(아직 계정이 없다면 그 페이지에서 먼저 가입하세요). 페이지에 인증 코드가 표시되는데, 터미널에 표시된 코드와 일치하는지 확인한 뒤에만 승인하세요. 로그인이 끝나면 터미널에 로그인되었다는 확인 메시지가 나타납니다.

인증 코드를 표시하는 Tripo CLI 브라우저 기기 인증 페이지

문제가 있나요? 브라우저가 열리지 않거나 로그인이 완료되지 않은 경우
  • 로그인이 완료되지 않은 경우: tripo login을 다시 실행하고, 터미널에 표시된 코드를 다시 확인한 뒤에만 승인하세요.
  • 브라우저가 아무 반응이 없는 경우: 터미널에 출력된 URL을 복사해 브라우저 주소창에 직접 붙여 넣으세요.
  • 브라우저 인증을 일시적으로 사용할 수 없는 경우: CLI가 대신 API 키 페이지를 엽니다. 이 섹션 끝의 "예비 로그인 방법과 리전"을 참고하세요.

3단계: 모든 준비가 끝났는지 확인

Bash
tripo doctor

로그인 상태, 네트워크 연결, 크레딧 잔액을 차례로 확인합니다. 세 가지가 모두 통과하면 설정이 완료된 것입니다.

문제가 있나요? 검사 중 하나가 실패한 경우
  • 인증 실패: 로그인이 완료되지 않은 상태입니다. tripo login을 실행해 다시 로그인하세요.
  • 네트워크 실패: 컴퓨터에서 웹 페이지가 열리는지 확인하세요. 회사나 학교 네트워크에서는 프록시가 필요할 수 있습니다.
  • 잔액 실패: 크레딧이 부족한 상태입니다. 아직 아무것도 생성되지 않았고 요금도 청구되지 않았습니다. tripo topup을 실행하면 결제 페이지가 열립니다.
예비 로그인 방법과 리전(브라우저 로그인을 사용할 수 없을 때만)
  • 이미 API 키가 있다면 tripo login --key tsk_...를 실행하거나 TRIPO_API_KEY 환경 변수를 설정하세요.
  • API 키는 계정 인증 정보입니다. 채팅, 소스 코드, 스크린샷, 로그에 절대 붙여 넣지 마세요.
  • 동일한 설치로 해외 계정과 중국 본토 계정을 모두 사용할 수 있습니다. CLI가 키로 두 리전을 모두 확인한 뒤 키가 허용된 리전을 자동으로 저장합니다.

첫 3D 모델 만들기

1단계: 문장 하나로 생성

따옴표 안의 문장이 프롬프트입니다. 만들고 싶은 것으로 자유롭게 바꾸세요.

Bash
tripo make "a cute low poly fox"

명령이 실행되는 동안 터미널을 닫지 마세요. Tripo CLI가 알맞은 워크플로와 모델을 선택하고, 작업이 끝날 때까지 기다린 뒤 현재 디렉터리의 tripo-out 폴더에 파일을 다운로드합니다. 전체 과정은 보통 몇 분 안에 끝나며 소량의 크레딧이 사용됩니다.

문제가 있나요? 생성이 시작되지 않거나 도중에 실패한 경우
  • 크레딧 부족: 모델 생성이 시작되지 않았고 요금도 청구되지 않았습니다. tripo topup으로 크레딧을 충전한 뒤 다시 시도하세요.
  • 네트워크 오류: 컴퓨터가 인터넷에 연결되어 있는지 확인한 뒤 같은 명령을 다시 실행하세요.
  • 작업 실패: 청구된 크레딧은 자동으로 환불됩니다. 다른 설명으로 다시 시도해 보세요.

2단계: 미리보기 열기

Bash
tripo view @last

@last는 "가장 최근 작업"을 뜻합니다. 브라우저에 드래그로 회전할 수 있는 대화형 3D 미리보기가 열립니다. 내가 만든 모델이 보인다면 성공입니다!

첫 성공 후: 지금 갖게 된 것들

  • 파일 위치: tripo-out 아래 새 폴더에 다운로드한 3D 모델과 작업이 어떻게 만들어졌는지 기록한 task.json이 저장됩니다. 서버가 미리보기 이미지를 제공하면 preview.png도 함께 저장됩니다.
  • 다시 열기: 언제든 tripo view @last를 실행하거나, tripo view <file>로 원하는 모델 파일을 열 수 있습니다.
  • 사용한 비용: tripo balance를 실행하면 크레딧 잔액을 확인할 수 있습니다.
  • 명령을 외우기 싫다면? tripo만 실행하면 안내형 대화 메뉴가 열립니다. 로그인, 생성, 미리보기, 충전을 모두 그 안에서 할 수 있습니다.
  • 다음 단계: 이미지로 생성하거나(다음 섹션), AI 어시스턴트에게 맡기거나(“AI 코딩 에이전트가 CLI를 능숙하게 다루게 하기”), 대량으로 처리해 보세요(“바로 쓰는 워크플로 및 파이프라인”).

이미지 또는 기존 모델로 생성하기

텍스트 예제가 성공했다면 로컬 파일도 전달할 수 있습니다. 아래의 concept.png, front.png, hero.glb는 예시 이름이므로 자신의 파일 경로로 바꾸세요.

Bash
tripo make concept.png --for print
tripo make front.png back.png
tripo make hero.glb --then texture,rig
tripo make @last --then convert:fbx
  • 1행: 콘셉트 이미지를 3D 프린팅에 바로 쓸 수 있는 모델로 만듭니다.
  • 2행: 앞면과 뒷면 이미지를 함께 사용해 더 정확한 디테일로 생성합니다.
  • 3행: 기존 모델에 텍스처와 리깅을 적용합니다.
  • 4행: 가장 최근 결과를 FBX로 변환합니다.

AI 코딩 에이전트가 CLI를 능숙하게 다루게 하기

AI 코딩 에이전트를 사용하지 않는다면 이 섹션을 건너뛰세요. npm 패키지에는 명령 참고 자료, 시나리오 레시피, 오류 복구 안내를 담은 Agent Skill이 포함되어 있어 에이전트가 CLI를 올바르게 사용할 수 있습니다. 에이전트에게 다음 명령을 실행하게 하면 전체 지침 또는 특정 주제 하나를 터미널에 출력합니다.

Bash
tripo docs --llm
tripo docs --topic commands/make
tripo docs --topic examples/game-asset
Skill에 포함된 파일 
skill/
├── SKILL.md
├── common-errors.md
├── commands/
│   ├── account.md
│   ├── batch.md
│   ├── generate.md
│   ├── make.md
│   ├── process.md
│   ├── task.md
│   └── view.md
└── examples/
    ├── animation.md
    ├── ar-web.md
    ├── film.md
    ├── game-asset.md
    ├── pipes.md
    └── print.md

명령어 참고

이 표를 외울 필요는 없습니다. 처음에는 tripo(대화형 메뉴), tripo make(생성), tripo view(미리보기), tripo doctor(상태 점검)만 있으면 일상적인 사용에 충분합니다. 나머지는 구체적인 필요가 생겼을 때 펼쳐 보세요.

전체 명령어 표와 공통 플래그 보기
명령어 기능
tripo make <input...> 명령 하나로 생성, 처리 및 다운로드
tripo ai [description] 작업을 계획하고 확인한 뒤 실행
tripo view [task|file] 대화형 로컬 3D 미리보기 열기
tripo redo [task] 새로운 시드로 요청 반복
tripo login / logout / whoami / use 명명된 계정 프로필 인증 및 전환
tripo topup / balance / usage 리전별 결제 페이지를 열고 크레딧 확인
tripo generate <endpoint> 8개의 모든 생성 엔드포인트에 명시적으로 액세스
tripo model / anim / mesh <step> 리파인, 텍스처, 리깅, 변환, 세그멘테이션 및 기타 처리 단계 실행
tripo task get/list/watch 작업 조회, 목록 표시 또는 완료 대기
tripo history [--limit <n>] 최근 로컬 작업 기록 표시
tripo files upload <path> 파일을 업로드하고 file_token 반환
tripo batch run <manifest.yaml> 동시 실행 및 재시도를 지원하는 재개 가능한 대량 파이프라인 실행
tripo config / doctor 설정 관리 및 로컬 환경 진단
tripo docs [--topic <topic>] 번들로 제공되는 Agent 및 명령어 문서 출력
tripo mcp CLI를 MCP 서버로 실행
tripo completion <shell> Bash, Zsh 또는 Fish용 자동 완성 생성

make, ai, generate 명령과 model, anim, mesh 아래의 처리 하위 명령은 -o/--out, --no-wait, --no-download, --name, --timeout, --notify 및 반복 가능한 --param key=value를 지원합니다. 전역 자동화 플래그에는 --json, --yes, --quiet, --no-open, --profile이 있습니다.

바로 쓰는 워크플로 및 파이프라인

이 섹션은 고급 내용이며 첫 생성에는 필요하지 않습니다. 7가지 내장 프리셋이 --for <preset> 하나로 유용한 매개변수와 처리 단계를 한꺼번에 적용합니다.

game-mobile · game-pc · film · print · ar-web · anim · toy

Bash
# Mobile game asset: low-poly generation, texture, then FBX
tripo make "sci-fi crate" --for game-mobile

# Print asset: watertight output, STL, and a flat bottom
tripo make "chess knight" --for print

# Explicit processing chain
tripo make cat.png --then texture,rig,convert:fbx

# The same chain as NDJSON pipes
tripo make cat.png --json | tripo model texture --json | tripo anim rig --json

# Resumable batch processing
tripo batch run assets.yaml --concurrency 2

@last, @2, @name 같은 작업 참조는 작업 ID를 받는 모든 위치에서 사용할 수 있습니다.

여러 계정 및 리전

Tripo 계정을 하나만 사용한다면 이 섹션을 건너뛰세요. 인증 정보는 명명된 프로필에 저장되므로 두 번째 계정에 로그인해도 첫 번째 계정을 덮어쓰지 않습니다.

Bash
tripo login
tripo login --profile work-cn
tripo use
tripo whoami
tripo make "a fox" --profile work-cn
tripo logout

각 프로필은 자체 키와 리전을 유지합니다. TRIPO_PROFILE 환경 변수는 현재 환경에서 사용할 프로필을 선택하고, TRIPO_API_KEY는 모든 프로필을 우회하며 가장 높은 우선순위를 갖습니다.

AI 코딩 에이전트 참고 사항

일반 사용자는 이 섹션을 건너뛸 수 있습니다. AI 코딩 에이전트가 작업을 올바르게 기다리고 기계 판독 출력을 처리하도록 돕는 규칙입니다.

  • tripo make와 tripo task watch는 블로킹 명령어입니다. 별도의 폴링 루프를 구현하지 말고 프로세스가 끝날 때까지 기다리세요.
  • --json을 사용하면 대부분의 일회성 명령은 stdout에 최종 JSON 한 줄을 출력합니다. 반면 tripo task watch --json은 NDJSON 진행 이벤트를 스트리밍한 뒤 최종 결과를 출력합니다.
  • preview.png가 있으면 확인한 후 파이프라인을 계속할지 또는 tripo redo를 실행할지 결정하세요.
  • 매개변수를 임의로 만들거나 레거시 모델 버전을 강제로 사용하지 마세요. 지원되는 플래그는 tripo docs --topic ...에서 확인하세요.
  • 로우 폴리 요청 또는 면 수 한도가 20,000 이하인 경우 tripo-p1이 선택되며, 그 밖의 작업은 기본적으로 tripo-v3.1을 사용합니다.
종료 코드 표 보기
종료 코드 의미
0 성공
1 예기치 않은 오류 또는 내부 오류
2 잘못된 사용법 또는 매개변수
3 인증 오류
4 크레딧 부족
5 콘텐츠 정책에 따른 거부
6 작업 실패. 크레딧은 자동으로 환불됩니다
7 네트워크 오류
8 리소스를 찾을 수 없음
9 요청 속도 제한. 백오프 후 다시 시도하세요

자동화용 환경 변수

일반적인 대화형 사용에는 환경 변수가 필요하지 않습니다. CI, 스크립트, 고급 에이전트 워크플로를 위한 것입니다. 그리고 잊지 마세요. API 키를 저장소에 커밋하거나 문서에 붙여 넣거나 스크린샷 또는 로그에 포함하지 마세요.

환경 변수 표 보기
변수 용도
TRIPO_API_KEY API 키. 가장 높은 우선순위를 가지며 CI 또는 Agent에 적합
TRIPO_PROFILE 명명된 계정 프로필. --profile과 동일
TRIPO_REGION 선택적 ov 또는 cn 재정의. 일반적으로 자동 감지
TRIPO_API_BASE_URL API 엔드포인트 재정의
TRIPO_PLATFORM_BASE_URL 플랫폼 엔드포인트 재정의
TRIPO_HOME 설정 및 기록 디렉터리. 기본값은 ~/.tripo
TRIPO_LLM_BASE_URL tripo ai용 선택적 OpenAI 호환 엔드포인트
TRIPO_LLM_API_KEY tripo ai용 선택적 LLM 키
TRIPO_LLM_MODEL tripo ai용 선택적 LLM 모델