建立 World

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": "夕陽下安靜的海邊小鎮，有狹窄小巷與溫暖燈光"
  }'

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"])

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);

{
  "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": {}
}

POST

worlds

generations

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": "夕陽下安靜的海邊小鎮，有狹窄小巷與溫暖燈光"
  }'

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"])

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);

{
  "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": {}
}

使用 World Labs Marble 生成可探索的 3D 世界。這是一個非同步 API：建立回應會返回任務識別，以及用於查詢狀態的 poll_url。透過 Models API 選擇目前可用的 Marble 模型。

請求主體

string

預設值:"marble-1.0"

透過 Models API 選擇目前可用的 Marble 模型。

string

用於純文字生成的文字提示詞，也可作為圖片或影片輸入時的引導。

object

提供給進階呼叫方的原生 World Labs world_prompt 物件。支援的提示類型包括 text、image、multi-image 與 video。

string

Base64 或 data URL 圖片提示。

string

圖片 URL 提示。

array

用於快捷多圖生成的多個圖片提示。最多提供 4 張圖片。若使用原生 World Labs 重建模式，請傳入 world_prompt.type="multi-image"、reconstruct_images: true，並最多提供 8 張圖片。

string

影片 URL 提示。

boolean | string

對於圖片輸入，設為 true 表示既有全景圖，false 表示普通單圖，或使用 auto。

integer

可選隨機種子，範圍為 0 到 4294967295。

string

可選的生成世界顯示名稱，最多 64 個字元。

array

可選的 World Labs 標籤。最多提供 10 個標籤，每個標籤最多 32 個字元。

object

可選的可見性與存取設定：public、allow_id_access、allowed_readers 和 allowed_writers。public: true 請求建立公開可見的 World。

回應

string

用於輪詢的公開任務 ID。

string

非同步任務識別別名。

string

World Labs 操作 ID。

string

此任務的建議輪詢 URL。

string

任務狀態：pending、processing、completed 或 failed。

string

生成完成後返回的 Marble 世界 URL。

string

可用時返回的碰撞網格 GLB URL。

string

可用時返回的全景圖 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": "夕陽下安靜的海邊小鎮，有狹窄小巷與溫暖燈光"
  }'

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"])

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);

授權

Authorization

string

header

必填

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

標頭

X-TokenLab-Delivery-Policy

enum<string>

單次請求傳輸策略。將覆蓋 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified，並可能在輸出、上游接收或持久化資源建立前，切換至僅使用 Official。

可用選項:

auto,

verified,

official

主體

application/json

world_prompt

object

必填

供進階呼叫者使用的原生 World Labs world_prompt 物件。支援的提示類型包括文字、圖片、多圖片和影片。內容參照可以使用 source=media_asset，並搭配由 /v1/worlds/media-assets/prepare-upload 準備的 media_asset_id。

model

enum<string>

預設值:marble-1.0

要使用的 Marble 模型。預設為 marble-1.0，以符合省略模型參數時目前的 World Labs 相容性預設值。

可用選項:

marble-1.0,

marble-1.1,

marble-1.1-plus

prompt

string

用於文字或引導式圖片/影片世界生成的文字提示。

display_name

string

生成世界的選填顯示名稱，最多 64 個字元。

Maximum string length: 64

image

string

Base64 或資料 URL 圖片提示。

image_url

string<uri>

圖片 URL 提示。

images

(string | object)[]

捷徑多圖片提示。最多提供 4 張圖片。使用原生 world_prompt.reconstruct_images=true 最多可提供 8 張圖片。

Maximum array length: 4

video_url

string<uri>

影片 URL 提示。

is_pano

圖片提示是否為現有的全景圖。使用 true 表示全景輸入，false 表示單張圖片輸入，或使用 auto。

seed

integer

選填的種子值，範圍從 0 到 4294967295。

必填範圍: 0 <= x <= 4294967295

回應

任務已建立

string

task_id

string

operation_id

string

status

enum<string>

可用選項:

pending,

processing,

completed,

failed

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

object

核心

文字

檔案與批次

圖像

音訊與即時

音樂

視頻與素材

Worlds

3D

非同步任務

Gemini 原生

管理

請求主體

回應

計費

授權

標頭

主體

回應

​請求主體

​回應

​計費

授權

標頭

主體

回應

請求主體

回應

計費