미디어 가이드
3D 생성
텍스트나 이미지로부터 다운로드 가능한 3D 모델 생성
3D 생성은 비동기 방식으로 이루어집니다. POST /v1/3d/generations는 TokenLab 작업을 생성하며, 완료된 상태 응답은 model_url 및 사용 가능한 경우 형식별 URL과 같은 다운로드 가능한 모델 에셋을 반환합니다.
다운로드 가능한 3D 모델 파일은 30일간 자동 보관되며, 해당 URL은 TokenLab 미디어 결과 URL입니다. 작업 기록 및 별도로 저장된 에셋은 자체 수명 주기를 따릅니다. 데이터 보존을 참조하십시오.
입력 유형 선택
| 입력 | 필수 | 선택적 필드 | 참고 |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | 설명으로부터 새로운 에셋을 생성하는 데 최적 |
| Image-to-3D | model, image_url 또는 image; 모델이 나열하는 경우 prompt 포함 | format, quality, style, seed | 선택한 모델이 이미지 입력을 지원하는 경우에만 사용 |
operation은 선택 사항이며 text-to-3d 또는 image-to-3d 중 하나입니다. 이를 생략하면 TokenLab은 image 또는 image_url을 보낼 때 image-to-3d를 사용하고, 그렇지 않으면 text-to-3d를 사용합니다. 값을 전달하는 경우 입력값과 일치해야 합니다. text-to-3d 모델은 프롬프트를 허용하며, image-to-3d 모델은 이미지 입력을 허용합니다.
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": "tripo-h3.1",
"prompt": "A stylized low-poly robot mascot with clean topology"
}'Image-to-3D의 경우, 인터넷에서 소스를 가져올 수 있을 때 https URL을 사용하십시오. 인라인 base64 image는 모델 세부 정보에 image가 나열된 경우에만 사용하십시오. 일부 모델은 image_url만 허용합니다.
출력 형식
glb는 웹 미리보기에 적합합니다.fbx및obj는 선택한 모델이 지원하는 경우 DCC 파이프라인에 유용합니다.usdz는 모델에서 제공하는 경우 Apple AR 워크플로우에 유용합니다.- 더 높은
quality값은 대기 시간과 비용을 증가시킬 수 있습니다. 사용자에게 이 선택 사항을 보여주십시오. seed는 이를 지원하는 모델에서만 반복 가능성에 영향을 미칩니다.
완성된 모델 가져오기
반환된 id 또는 task_id를 사용하여 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로 대체하거나 해당 형식을 지원하는 모델 선택 |
| Image-to-3D 거부됨 | 선택한 모델이 텍스트 전용이거나 이미지 URL에 접근할 수 없음 | 모델 세부 정보를 확인하고 URL 유효성 검사 |
| 중복 에셋 | 재시도 경로에서 타임아웃 후 작업을 다시 생성함 | 재시도 전 작업 식별자 저장 |
API 참조
| 주제 | 참조 |
|---|---|
| 3D 생성 | Create 3D |
| 3D 상태 가져오기 | Get 3D Status |
| 작업 상태 가져오기 | 작업 상태 가져오기 |
| 모델 목록 | 모델 목록 조회 |
| 결제 및 가격 | Billing & Pricing |