TokenLab

Worlds

建立世界

建立 World Labs Marble 世界生成任務

POST
/v1/worlds/generations

使用 World Labs Marble 生成可探索的 3D 世界。這是一個非同步 API:建立請求的回應會返回任務識別碼。請使用該任務 id 輪詢 GET /v1/tasks/{id} 以獲取狀態。

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

請求主體

modelstring預設值: marble-1.0

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

promptstring

僅文字生成的文字提示詞,或用於圖像與影片輸入的引導提示詞。最多 4000 個字元。請發送 world_prompt、prompt、image、image_url、images 或 video_url 中至少一個欄位。

world_promptobject

供進階呼叫者使用的原生 World Labs world_prompt 物件。支援的提示詞類型為 text、image、multi-image 和 video。內容參照可指向您透過 準備媒體資產上傳 上傳的檔案:{ "source": "media_asset", "media_asset_id": "..." }。

imagestring

Base64 或 Data URL 圖像提示詞。

image_urlstring

圖像 URL 提示詞。

imagesarray

用於快捷多圖生成的多個圖像提示詞。最多提供 4 張圖像,每張圖像可為 URL、Base64 或 Data URL 字串,或是包含 uri、image_url 或 url 以及可選 azimuth 數值的物件。若使用原生 World Labs 重建模式,請傳入 world_prompt.type="multi-image" 並設定 reconstruct_images: true,最多可提供 8 張圖像。

video_urlstring

影片 URL 提示詞。

is_panoboolean | string

針對圖像輸入,若是既有的全景圖請設定為 true,一般單張圖像設定為 false,或設定為 auto。

seedinteger

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

display_namestring

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

tagsarray

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

permissionobject

可選的公開性與存取設定:public、allow_id_access、allowed_readers 和 allowed_writers。public: true 代表請求公開可見的世界。

回應

idstring

公開任務 ID。請使用它輪詢 GET /v1/tasks/{id}。

task_idstring

非同步任務識別碼別名。

operation_idstring

World Labs 操作 ID。

poll_urlstring

位於 /v1/worlds/generations/{id} 下的世界狀態 URL。此為相容性端點,請改用 id 輪詢 GET /v1/tasks/{id}。

statusstring

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

world_marble_urlstring

完成時生成的 Marble 世界 URL。

glb_urlstring

碰撞網格 GLB URL(若可用)。

pano_urlstring

全景圖像 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
AuthorizationBearer <token>

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

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

選填鍵值,使建立請求可安全重試。請為每個任務發送一個新的唯一值(例如 UUID)。使用相同鍵值與相同主體的重試會回傳原始建立請求的結果(通常是原始任務),且不會建立、分發或扣款第二次任務。若使用已接受的鍵值但主體不同,則會回傳 409 錯誤。超過 255 個字元的鍵值將被忽略,該請求將不具備冪等性保護。請參閱 安全地使用冪等鍵進行重試。

長度1 <= length <= 255

請求主體

application/json

回應

application/json

application/json

application/json

application/json

application/json