World 생성

World Labs Marble로 탐색 가능한 3D 월드를 생성합니다. 이 API는 비동기 방식이며, 생성 응답에는 작업 식별자와 상태 확인용 poll_url이 포함됩니다.

Models API에서 현재 사용 가능한 Marble 모델을 선택하세요.

요청 본문

modelstring기본값: marble-1.0

Models API에서 현재 사용 가능한 Marble 모델을 선택하세요.

promptstring

텍스트 전용 생성 또는 이미지/비디오 입력의 가이드로 사용할 텍스트 프롬프트입니다.

world_promptobject

고급 호출자를 위한 네이티브 World Labs world_prompt 객체입니다. 지원 타입은 text, image, multi-image, video입니다.

imagestring

Base64 또는 data URL 이미지 프롬프트입니다.

image_urlstring

이미지 URL 프롬프트입니다.

imagesarray

간편 multi-image 생성을 위한 여러 이미지 프롬프트입니다. 최대 4장까지 제공할 수 있습니다. 네이티브 World Labs 재구성 모드에서는 world_prompt.type="multi-image", reconstruct_images: true와 함께 최대 8장을 전달하세요.

video_urlstring

비디오 URL 프롬프트입니다.

is_panoboolean | string

이미지 입력에서 기존 파노라마는 true, 일반 단일 이미지는 false, 또는 auto를 설정합니다.

seedinteger

선택적 시드입니다. 0부터 4294967295까지 가능합니다.

display_namestring

선택적 업스트림 월드 표시 이름입니다. 최대 64자입니다.

tagsarray

선택적 업스트림 태그입니다. 최대 10개, 각 태그는 최대 32자입니다.

permissionobject

선택적 공개 범위 및 접근 설정: public, allow_id_access, allowed_readers, allowed_writers. public: true는 공개적으로 볼 수 있는 월드 생성을 요청합니다.

응답

idstring

폴링에 사용할 공개 작업 ID입니다.

task_idstring

비동기 작업 식별자 별칭입니다.

operation_idstring

업스트림 World Labs 작업 ID입니다.

poll_urlstring

이 작업의 권장 폴링 URL입니다.

statusstring

작업 상태: pending, processing, completed, failed.

world_marble_urlstring

완료 시 생성된 Marble 월드 URL입니다.

glb_urlstring

사용 가능한 경우 collider mesh GLB URL입니다.

pano_urlstring

사용 가능한 경우 파노라마 이미지 URL입니다.

가격

현재 요금은 Pricing API를 확인하세요. 최종 청구 금액은 사용량 기록에 표시됩니다. 반환된 cost.total_credits는 생성 사용량이며 통화 금액이 아닙니다.

요청

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": "해 질 녘 조용한 해안 마을, 좁은 골목과 따뜻한 불빛"
  }'

{  "id": "string",  "task_id": "string",  "operation_id": "string",  "status": "pending",  "poll_url": "string",  "world_id": "string",  "world_marble_url": "string",  "model_url": "string",  "glb_url": "string",  "pano_url": "string",  "thumbnail_url": "string",  "caption": "string",  "cost": {},  "error": "string",  "error_details": {    "projection_version": 0,    "status": 400,    "message": "string",    "type": "string",    "code": "string",    "param": "string",    "retryable": true,    "upstream": {      "source": "string",      "code": "string",      "message": "string",      "param": "string"    }  }}

인증

BearerAuth

AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

"auto"
"verified"
"official"

요청 본문

application/json

model?string

사용할 Marble 모델입니다. 모델이 생략된 경우 현재 World Labs 호환성 기본값에 맞춰 marble-1.0이 기본값으로 설정됩니다.

기본값"marble-1.0"

허용 값

"marble-1.0"
"marble-1.1"
"marble-1.1-plus"

prompt?string

텍스트 또는 가이드 이미지/비디오 월드 생성에 사용되는 텍스트 프롬프트입니다.

display_name?string

생성된 월드에 대한 선택적 표시 이름으로, 최대 64자까지 가능합니다.

길이length <= 64

world_prompt*

고급 호출자를 위한 네이티브 World Labs world_prompt 객체입니다. 지원되는 프롬프트 유형은 텍스트, 이미지, 다중 이미지, 비디오입니다. 콘텐츠 참조는 /v1/worlds/media-assets/prepare-upload를 통해 준비된 media_asset_id와 함께 source=media_asset을 사용할 수 있습니다.

image?string

Base64 또는 데이터 URL 이미지 프롬프트입니다.

image_url?string

이미지 URL 프롬프트입니다.

형식uri

images?array<string|>

단축 다중 이미지 프롬프트입니다. 최대 4개의 이미지를 제공하십시오. 최대 8개의 이미지를 사용하려면 네이티브 world_prompt.reconstruct_images=true를 사용하십시오.

항목items <= 4

video_url?string

비디오 URL 프롬프트입니다.

형식uri

is_pano?|

이미지 프롬프트가 기존 파노라마인지 여부입니다. 파노라마 입력에는 true, 단일 이미지 입력에는 false 또는 auto를 사용하십시오.

seed?integer

0에서 4294967295 사이의 선택적 시드(seed)입니다.

범위0 <= value <= 4294967295

tags?array<>

선택적 World Labs 태그입니다. 최대 10개의 태그를 제공할 수 있으며, 각 태그는 최대 32자까지 가능합니다.

항목items <= 10

permission?

선택적 World Labs 권한 객체입니다.

user?string

최종 사용자 식별자.

World 생성

요청 본문

응답

가격

인증

헤더

요청 본문

응답

`application/json`

`application/json`

`application/json`

World 생성

요청 본문Copy Anchor Link

응답Copy Anchor Link

가격Copy Anchor Link

인증Copy Anchor Link

헤더Copy Anchor Link

요청 본문Copy Anchor Link

응답Copy Anchor Link

200application/json

401application/json

503application/json

요청 본문

응답

가격

인증

헤더

요청 본문

응답

`application/json`

`application/json`

`application/json`