Worlds
建立 World
建立一個 World Labs Marble 世界生成任務
使用 World Labs Marble 生成可探索的 3D 世界。這是一個非同步 API：建立回應會返回任務識別，以及用於查詢狀態的 poll_url。
透過 Models API 選擇目前可用的 Marble 模型。
請求主體
marble-1.0透過 Models API 選擇目前可用的 Marble 模型。
用於純文字生成的文字提示詞，也可作為圖片或影片輸入時的引導。
提供給進階呼叫方的原生 World Labs world_prompt 物件。支援的提示類型包括 text、image、multi-image 與 video。
Base64 或 data URL 圖片提示。
圖片 URL 提示。
用於快捷多圖生成的多個圖片提示。最多提供 4 張圖片。若使用原生 World Labs 重建模式，請傳入 world_prompt.type="multi-image"、reconstruct_images: true，並最多提供 8 張圖片。
影片 URL 提示。
對於圖片輸入，設為 true 表示既有全景圖，false 表示普通單圖，或使用 auto。
可選隨機種子，範圍為 0 到 4294967295。
可選的生成世界顯示名稱，最多 64 個字元。
可選的 World Labs 標籤。最多提供 10 個標籤，每個標籤最多 32 個字元。
可選的可見性與存取設定：public、allow_id_access、allowed_readers 和 allowed_writers。public: true 請求建立公開可見的 World。
回應
用於輪詢的公開任務 ID。
非同步任務識別別名。
World Labs 操作 ID。
此任務的建議輪詢 URL。
任務狀態：pending、processing、completed 或 failed。
生成完成後返回的 Marble 世界 URL。
可用時返回的碰撞網格 GLB URL。
可用時返回的全景圖 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 API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified，並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
請求主體
application/json
回應
application/json
application/json
application/json