미디어 가이드
Worlds
텍스트, 이미지 또는 비디오로부터 탐색 가능한 Marble 월드를 생성합니다
Worlds는 사용자가 열어서 탐색할 수 있는 Marble 환경을 생성합니다. 환경 대신 다운로드 가능한 객체가 필요한 경우 3D generation을 사용하십시오.
splat, mesh, 파노라마 이미지와 같은 다운로드 가능한 World 파일은 TokenLab 미디어 결과 URL과 함께 30일 동안 자동으로 보관됩니다. 대화형 World 페이지와 World 레코드는 그렇지 않습니다. 데이터 보존을 참조하십시오.
입력 및 미디어 에셋
월드는 모델에 따라 텍스트, 하나 이상의 이미지 또는 비디오에서 시작할 수 있습니다. GET /v1/models?recommended_for=3d에서 Marble 모델(marble-*)을 찾으십시오. 해당 작업은 world-generation입니다. 최소 하나의 입력을 전송하십시오:
| 입력 | 필드 |
|---|---|
| 텍스트 | prompt, 최대 4,000자 |
| 이미지 1개 | image_url 또는 Base64/데이터 URL 형식의 image; is_pano는 파노라마 여부를 나타냄 |
| 이미지 여러 개 | images, 최대 4개 |
| 비디오 | video_url |
| 고급 | world_prompt, 업로드된 미디어 에셋을 참조할 수 있는 네이티브 프롬프트 객체 |
선택적 필드로는 display_name(최대 64자), seed, tags(최대 10개), permission이 있습니다. 재사용 가능한 미디어는 한 번 업로드한 후 에셋 ID로 참조할 수 있습니다.
미디어 및 World 레코드에 대한 액세스 권한은 API 키를 소유한 조직을 기준으로 확인됩니다. 월드를 공유하기 전에 선택한 모델의 permission 옵션을 검토하십시오. 반환된 에셋 또는 뷰어 URL에는 자체적인 액세스 규칙이 있을 수 있습니다.
생성 및 폴링
생성 응답에는 작업 ID와 일반적으로 poll_url이 포함됩니다. ID를 보관한 다음, 상태가 completed 또는 failed가 될 때까지 해당 ID로 GET /v1/tasks/{id}를 호출하십시오. Worlds의 poll_url은 호환성 경로인 /v1/worlds/generations/{id}를 가리킵니다. 대신 /v1/tasks/{id}를 사용하십시오.
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"
}'생성 응답의 id를 사용하여 작업을 폴링하십시오:
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"완료된 월드 관리
계정에서 완료된 월드를 확인하려면 POST /v1/worlds/list 및 GET /v1/worlds/{id}를 사용하고, 월드를 삭제하려면 DELETE /v1/worlds/{id}를 사용하십시오. 보류 중이거나 실패한 생성 작업에는 GET /v1/tasks/{id}를 사용하십시오. 사용자가 제품에서 생성된 월드를 의도적으로 제거할 때만 삭제하십시오.
일반적인 주의 사항
- 모든 월드 모델이 모든 입력 유형을 지원한다고 가정하지 마십시오.
- 서명된 이미지 또는 비디오 URL이 서비스 재시도 요청을 처리할 수 있을 만큼 충분히 유효한지 확인하십시오.
- 타임아웃 후 재시도하기 전에 반환된 작업 ID를 저장하십시오.
- 탐색 가능한 월드 대신 다운로드 가능한 모델 파일이 필요한 경우 3D generation을 사용하십시오.
API 참조
| 주제 | 참조 |
|---|---|
| 월드 생성 | 월드 생성 |
| 작업 상태 가져오기 | 작업 상태 가져오기 |
| 월드 상태 가져오기 (호환성) | 월드 상태 가져오기 |
| 미디어 에셋 업로드 준비 | 미디어 에셋 업로드 준비 |
| 미디어 에셋 가져오기 | 미디어 에셋 조회 |
| 월드 목록 | 월드 목록 조회 |
| 월드 가져오기 | World 조회 |
| 월드 삭제 | 월드 삭제 |
| 비동기 작업 | Async Jobs |
| 3D 생성 가이드 | 3D Generation Guide |