메인 콘텐츠로 건너뛰기
3D 생성은 비동기적입니다. POST /v1/3d/generations는 TokenLab 작업을 생성하며, 완료 상태 응답은 model_url과 같은 다운로드 가능한 모델 자산을 반환하고, 사용 가능한 경우 형식별 URL을 반환합니다.

​
입력 유형 선택

워크플로우필수 입력선택적 필드비고
텍스트-투-3Dmodel, promptformat, quality, style, seed설명에서 새로운 자산을 생성하는 데 가장 적합합니다.
이미지-투-3Dmodel, prompt, image 또는 image_urlformat, quality, style, seed선택한 모델이 이미지 입력을 지원할 때만 사용하십시오.
어떤 옵션을 노출할지 결정하기 전에 모델 카탈로그를 쿼리하십시오: 
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
모든 3D 모델이 두 가지 입력 유형을 지원하거나 모든 출력 형식을 지원한다고 가정하지 마십시오. image, image_url, format, quality, style, 또는 seed를 전송하기 전에 선택한 모델 계약을 확인하십시오.

​
3D 작업 생성

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "깔끔한 토폴로지를 가진 스타일화된 로우 폴리 로봇 마스코트",
    "format": "glb",
    "quality": "standard"
  }'
이미지-투-3D의 경우 가능한 경우 공개 image_url을 사용하십시오. 클라이언트가 의도적으로 비공식 미디어를 전송하고 백엔드가 더 큰 요청 본문을 처리할 준비가 되어 있을 때만 인라인/base64 image를 사용하십시오.

​
출력 형식 선택

  • glb는 일반적으로 웹 미리보기를 위한 가장 안전한 기본값입니다.
  • fbx 및 obj는 선택한 모델이 이를 지원할 때 DCC 파이프라인에 유용합니다.
  • usdz는 모델이 노출할 때 Apple AR 워크플로우에 유용합니다.
  • 더 높은 quality 값은 대기 시간과 비용을 증가시킬 수 있습니다. 이를 숨겨진 기본값이 아닌 명시적인 사용자 선택으로 노출하십시오.
  • seed는 모델이 이를 존중할 때만 재현 가능성에 유용합니다.

​
자산 폴링 및 저장

반환된 poll_url을 먼저 사용하십시오. 클라이언트가 고정 경로가 필요하면 GET /v1/tasks/{id}를 사용하십시오. 
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
완료된 작업은 model_url을 반환하며 glb_url, fbx_url, obj_url, 또는 usdz_url을 포함할 수 있습니다. 사용자가 반복 접근, 버전 기록 또는 장기 다운로드가 필요할 경우 선택한 자산을 다운로드하거나 캐시하십시오.

​
생산 체크리스트

  • task_id, poll_url, 모델, 요청된 형식 및 자신의 자산 기록 ID를 유지하십시오.
  • 페이지 새로 고침 후에는 중복 작업을 생성하는 대신 폴링을 재개하십시오.
  • 작업을 생성하기 전에 소스 이미지 크기와 접근 가능성을 검증하십시오.
  • 사용자가 자산에 접근할 권한이 없는 한 생성된 자산 URL을 공개 페이지에 두지 마십시오.
  • 나중에 조정을 위해 존재할 경우 billing_transaction_id를 기록하십시오.

​
일반 오류

증상가능한 원인수정
생성 응답에 자산 URL 없음3D 생성은 비동기적입니다.최종 상태까지 폴링하십시오.
요청된 형식 없음모델이 해당 형식을 반환하지 않았습니다.model_url로 대체하거나 형식을 지원하는 모델을 선택하십시오.
이미지-투-3D 거부됨선택한 모델이 텍스트 전용이거나 이미지 URL에 접근할 수 없습니다.모델 계약을 확인하고 URL을 검증하십시오.
중복 자산재시도 경로가 타임아웃 후 작업을 재생성했습니다.재시도하기 전에 작업 ID를 저장하십시오.

​
API 참조

주제참조
3D 생성3D 생성
3D 상태 가져오기3D 상태 가져오기
작업 상태 가져오기작업 상태 가져오기
모델 목록모델 목록
청구 및 가격 책정청구 및 가격 책정