> ## 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">
  用於快捷多圖生成的多個圖片提示。最多提供 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">
  可選的 World Labs 標籤。最多提供 10 個標籤，每個標籤最多 32 個字元。
</ParamField>

<ParamField body="permission" type="object">
  可選的 World Labs 權限物件。
</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">
  可用時返回的碰撞網格 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 歸屬的媒體資產和已完成生成的 worlds。TokenLab 仍不開放 `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>