TokenLab

Worlds

월드 생성

World Labs Marble 월드 생성 작업을 생성합니다

POST
/v1/worlds/generations

World Labs Marble을 사용하여 탐색 가능한 3D 월드를 생성합니다. 이 API는 비동기식 API로, 생성 요청에 대한 응답으로 작업 식별자를 반환합니다. 작업 상태를 확인하려면 작업 id를 사용하여 GET /v1/tasks/{id}를 폴링하세요.

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

요청 본문

modelstring기본값: marble-1.0

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

promptstring

텍스트 전용 생성을 위한 텍스트 프롬프트 또는 이미지 및 비디오 입력을 위한 가이드 프롬프트입니다. 최대 4,000자까지 지원됩니다. world_prompt, prompt, image, image_url, images 또는 video_url 중 하나 이상을 전송해야 합니다.

world_promptobject

고급 사용자를 위한 기본 World Labs world_prompt 객체입니다. 지원되는 프롬프트 유형은 text, image, multi-image, video입니다. 콘텐츠 참조는 미디어 에셋 업로드 준비를 통해 업로드한 파일을 가리킬 수 있습니다: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

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

image_urlstring

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

imagesarray

간편한 다중 이미지 생성을 위한 복수 이미지 프롬프트입니다. 최대 4개의 이미지를 제공할 수 있으며, 각각 URL, Base64 또는 데이터 URL 문자열, 또는 uri, image_url, url 및 선택적 azimuth 숫자가 포함된 객체일 수 있습니다. 기본 World Labs 재구성 모드를 사용하려면 reconstruct_images: true 및 최대 8개의 이미지와 함께 world_prompt.type="multi-image"를 전달하세요.

video_urlstring

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

is_panoboolean | string

이미지 입력 시 기존 파노라마인 경우 true, 일반 단일 이미지인 경우 false 또는 auto로 설정합니다.

seedinteger

선택 사항인 시드값으로, 0부터 4294967295까지의 정수입니다.

display_namestring

생성된 월드의 표시 이름(선택 사항)으로, 최대 64자까지 가능합니다.

tagsarray

선택 사항인 World Labs 태그입니다. 각 최대 32자의 태그를 최대 10개까지 제공할 수 있습니다.

permissionobject

선택 사항인 공개 여부 및 접근 설정입니다: public, allow_id_access, allowed_readers, allowed_writers. public: true로 설정하면 공개적으로 표시되는 월드를 요청합니다.

응답

idstring

공개 작업 ID입니다. 이 ID로 GET /v1/tasks/{id}를 폴링하세요.

task_idstring

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

operation_idstring

World Labs 작업 ID입니다.

poll_urlstring

/v1/worlds/generations/{id} 경로의 월드 상태 URL입니다. 이는 호환성을 위한 엔드포인트입니다. 대신 id를 사용하여 GET /v1/tasks/{id}를 폴링하세요.

statusstring

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

world_marble_urlstring

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

glb_urlstring

사용 가능한 경우 콜라이더 메시 GLB URL입니다.

pano_urlstring

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

요금 안내

현재 요금은 Pricing API를 참조하세요. 최종 청구 금액은 사용 내역에 표시됩니다.

오류

  • 400 invalid_request: 프롬프트 입력이 전송되지 않았거나 필드 값이 범위를 벗어났습니다. param에 해당 필드명이 표시됩니다.
  • 400 model_not_found 또는 unsupported_endpoint: 호출 가능한 Marble 모델이 아닙니다.
  • 403 media_asset_not_owned 또는 404 media_asset_not_found: world_prompt의 media_asset_id가 다른 Workspace에 속해 있거나 존재하지 않습니다.
  • 402: 작업을 시작하기에 잔액이 부족합니다.

요청

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": "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",  "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"
Idempotency-Key?string

생성 요청을 안전하게 재시도할 수 있게 하는 선택적 키입니다. 각 작업마다 UUID와 같은 새로운 고유 값을 전송하십시오. 동일한 키와 동일한 본문으로 재시도하면 원래 생성 요청의 결과(일반적으로 원래 작업)가 반환되며, 두 번째 작업이 생성, 발송 또는 청구되지 않습니다. 이미 수락된 키와 다른 본문을 전송하면 409 오류가 발생합니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성 보호를 받지 못합니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.

길이1 <= length <= 255

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json