> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# World 생성

> World Labs Marble 월드 생성 작업을 만듭니다

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

지원 모델은 `marble-1.0`, `marble-1.1`, `marble-1.1-plus`입니다. World Labs 문서에는 `marble-1.0-draft`도 있지만, TokenLab은 아직 이 엔드포인트에서 draft 생성을 노출하지 않습니다.

## 요청 본문

<ParamField body="model" type="string" default="marble-1.0">
  사용할 Marble 모델: `marble-1.0`, `marble-1.1`, `marble-1.1-plus`.
</ParamField>

<ParamField body="prompt" type="string">
  텍스트 전용 생성 또는 이미지/비디오 입력의 가이드로 사용할 텍스트 프롬프트입니다.
</ParamField>

<ParamField body="world_prompt" type="object">
  고급 호출자를 위한 네이티브 World Labs `world_prompt` 객체입니다. 지원 타입은 `text`, `image`, `multi-image`, `video`입니다.
</ParamField>

<ParamField body="image" type="string">
  Base64 또는 data URL 이미지 프롬프트입니다.
</ParamField>

<ParamField body="image_url" type="string">
  이미지 URL 프롬프트입니다.
</ParamField>

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

<ParamField body="video_url" type="string">
  비디오 URL 프롬프트입니다.
</ParamField>

<ParamField body="is_pano" type="boolean | string">
  이미지 입력에서 기존 파노라마는 `true`, 일반 단일 이미지는 `false`, 또는 `auto`를 설정합니다.
</ParamField>

<ParamField body="seed" type="integer">
  선택적 시드입니다. 0부터 4294967295까지 가능합니다.
</ParamField>

<ParamField body="display_name" type="string">
  선택적 업스트림 월드 표시 이름입니다. 최대 64자입니다.
</ParamField>

<ParamField body="tags" type="array">
  선택적 업스트림 태그입니다. 최대 10개, 각 태그는 최대 32자입니다.
</ParamField>

<ParamField body="permission" type="object">
  선택적 World Labs permission 객체입니다.
</ParamField>

## 응답

<ResponseField name="id" type="string">
  폴링에 사용할 공개 작업 ID입니다.
</ResponseField>

<ResponseField name="task_id" type="string">
  비동기 작업 식별자 별칭입니다.
</ResponseField>

<ResponseField name="operation_id" type="string">
  업스트림 World Labs 작업 ID입니다.
</ResponseField>

<ResponseField name="poll_url" type="string">
  이 작업의 권장 폴링 URL입니다.
</ResponseField>

<ResponseField name="status" type="string">
  작업 상태: `pending`, `processing`, `completed`, `failed`.
</ResponseField>

<ResponseField name="world_marble_url" type="string">
  완료 시 생성된 Marble 월드 URL입니다.
</ResponseField>

<ResponseField name="glb_url" type="string">
  사용 가능한 경우 collider mesh GLB URL입니다.
</ResponseField>

<ResponseField name="pano_url" type="string">
  사용 가능한 경우 파노라마 이미지 URL입니다.
</ResponseField>

## 가격

World Labs는 credits 단위로 과금합니다. TokenLab은 요청 유형별 최대치를 먼저 차감하고, 완료된 operation에서 `cost.total_credits`를 받을 수 있으면 실제 credits 기준으로 정산합니다. 표준 Marble 요청은 최대 1,600 credits, `marble-1.1-plus` 요청은 최대 3,100 credits입니다.

## 범위

이 관리 엔드포인트는 TokenLab 소유 미디어 자산과 완료된 생성 world를 다룹니다. `marble-1.0-draft` 생성과 독립 pano/depth 도구는 아직 제공하지 않습니다.

<RequestExample>
  ```bash cURL theme={null}
  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": "해 질 녘 조용한 해안 마을, 좁은 골목과 따뜻한 불빛"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tokenlab.sh/v1/worlds/generations",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={
          "model": "marble-1.1",
          "prompt": "해 질 녘 조용한 해안 마을, 좁은 골목과 따뜻한 불빛",
      },
  )

  task = response.json()
  print(task["id"], task["poll_url"])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tokenlab.sh/v1/worlds/generations', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'marble-1.1',
      prompt: '해 질 녘 조용한 해안 마을, 좁은 골목과 따뜻한 불빛'
    })
  });

  const task = await response.json();
  console.log(task.id, task.poll_url);
  ```
</RequestExample>