Worlds
建立世界
建立 World Labs Marble 世界生成任務
使用 World Labs Marble 生成可探索的 3D 世界。這是一個非同步 API:建立請求的回應會返回任務識別碼。請使用該任務 id 輪詢 GET /v1/tasks/{id} 以獲取狀態。
使用 Models API 選擇目前可用的 Marble 模型。
請求主體
marble-1.0使用 Models API 選擇目前可用的 Marble 模型。
僅文字生成的文字提示詞,或用於圖像與影片輸入的引導提示詞。最多 4000 個字元。請發送 world_prompt、prompt、image、image_url、images 或 video_url 中至少一個欄位。
供進階呼叫者使用的原生 World Labs world_prompt 物件。支援的提示詞類型為 text、image、multi-image 和 video。內容參照可指向您透過 準備媒體資產上傳 上傳的檔案:{ "source": "media_asset", "media_asset_id": "..." }。
Base64 或 Data URL 圖像提示詞。
圖像 URL 提示詞。
用於快捷多圖生成的多個圖像提示詞。最多提供 4 張圖像,每張圖像可為 URL、Base64 或 Data URL 字串,或是包含 uri、image_url 或 url 以及可選 azimuth 數值的物件。若使用原生 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 代表請求公開可見的世界。
回應
公開任務 ID。請使用它輪詢 GET /v1/tasks/{id}。
非同步任務識別碼別名。
World Labs 操作 ID。
位於 /v1/worlds/generations/{id} 下的世界狀態 URL。此為相容性端點,請改用 id 輪詢 GET /v1/tasks/{id}。
任務狀態:pending、processing、completed 或 failed。
完成時生成的 Marble 世界 URL。
碰撞網格 GLB URL(若可用)。
全景圖像 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 API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
選填鍵值,使建立請求可安全重試。請為每個任務發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳原始建立請求的結果(通常是原始任務),且不會建立、分發或扣款第二次任務。若使用已接受的鍵值但主體不同,則會回傳 409 錯誤。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。
1 <= length <= 255請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json