미디어 가이드
Worlds
탐색 가능한 Worlds를 생성하고, 미디어 프롬프트를 업로드하고, 작업을 polling하며 완료된 World를 관리합니다.
World 생성은 탐색 가능한 Marble World를 비동기로 만듭니다. 사용자가 열거나 다시 방문할 수 있는 환경이 출력이면 Worlds를 사용하세요. 다운로드 가능한 단독 모델 asset이 필요하면 3D 생성을 사용하세요.
입력과 미디어 asset
World 작업은 선택한 모델과 요청 형태에 따라 텍스트, 이미지, 여러 이미지, 동영상에서 시작할 수 있습니다. 재사용 가능한 미디어 프롬프트는 먼저 media asset으로 준비한 뒤 World 요청에서 참조하세요.
미디어와 월드 기록 접근은 API 키의 소유 조직을 기준으로 확인합니다. 월드를 공유하기 전에 모델의 permission 옵션을 확인하세요. 반환된 자산이나 뷰어 URL에는 별도 접근 규칙이 있을 수 있습니다.
생성과 polling
생성 응답에는 공개 task ID와 보통 poll_url이 포함됩니다. 진행률을 보여주기 전에 ID를 저장하고 poll_url 또는 GET /v1/tasks/{id}를 completed 또는 failed까지 확인하세요.
curl -X POST "https://api.tokenlab.sh/v1/worlds/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "marble-1.1",
"prompt": "A quiet coastal town at sunset with narrow alleys and warm lights"
}'완료된 Worlds 관리
Worlds list/get endpoint는 내 계정에서 사용할 수 있는 완료 결과용입니다. pending 또는 failed 생성 작업은 task status endpoint를 사용하세요. delete는 사용자가 생성 World 삭제를 명확히 선택했을 때만 호출하세요.
흔한 실수
- 모든 World 모델이 모든 입력 유형을 지원한다고 가정하지 마세요.
- 서명된 이미지나 동영상 URL은 서비스 가져오기 재시도를 견딜 만큼 오래 유지하세요.
- timeout 뒤 재시도하기 전에 반환된 task ID를 저장하고 조회하세요.
- 다운로드 가능한 모델 파일이 필요하면 Worlds가 아니라 3D 생성을 사용하세요.
API 레퍼런스
| 주제 | 레퍼런스 |
|---|---|
| World 생성 | World 생성 |
| World 상태 조회 | World 상태 조회 |
| 미디어 asset 업로드 준비 | 미디어 asset 업로드 준비 |
| 미디어 asset 조회 | 미디어 asset 조회 |
| Worlds 목록 | Worlds 목록 |
| World 조회 | World 조회 |
| World 삭제 | World 삭제 |
| 비동기 작업 | 비동기 작업 |
| 3D 생성 가이드 | 3D 생성 가이드 |