TokenLab

媒體指南

Worlds

透過文字、圖片或影片建立可探索的 Marble 世界

Worlds 可建立一個供人們開啟並探索的 Marble 環境。如果您需要的是可下載的物件而非環境,請使用 3D generation。

可下載的 World 檔案(例如 splats、meshes 和全景圖片)會作為自動 30 天備份保留,並附帶 TokenLab media-result URL。互動式 World 頁面與 World 記錄則不會保留。請參閱 資料保留。

輸入與媒體資產

根據模型的不同,世界可以從文字、一張或多張圖片,或是影片開始建立。請在 GET /v1/models?recommended_for=3d 中尋找 Marble 模型(marble-*);其操作為 world-generation。請至少發送一個輸入:

輸入欄位
文字prompt,最多 4,000 個字元
單張圖片image_url,或作為 Base64 或資料 URL 的 image;is_pano 用於標示是否已為全景圖
多張圖片images,最多 4 張
影片video_url
進階world_prompt,一個可參照已上傳媒體資產的原生 prompt 物件

選填欄位包括 display_name(最多 64 個字元)、seed、tags(最多 10 個)以及 permission。可重複使用的媒體可以上傳一次,並透過其資產 ID 進行參照。

對媒體和 World 記錄的存取權限會根據擁有該 API key 的組織進行檢查。在分享世界之前,請先檢閱所選模型的 permission 選項;回傳的資產或檢視器 URL 可能會有其各自的存取規則。

建立與輪詢 (Create And Poll)

建立回應包含一個任務 ID 以及通常會有的 poll_url。請保留該 ID,並持續呼叫 GET /v1/tasks/{id},直到狀態變為 completed 或 failed 為止。Worlds 的 poll_url 指向 /v1/worlds/generations/{id}(一個相容性路徑)。請改用 /v1/tasks/{id}。

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 來輪詢任務:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

管理已完成的世界

使用 POST /v1/worlds/list 和 GET /v1/worlds/{id} 來存取您帳戶中已完成的世界,並使用 DELETE /v1/worlds/{id} 來移除它們。對於待處理或失敗的生成任務,請使用 GET /v1/tasks/{id}。僅在使用者有意從您的產品中移除已生成的世界時才執行刪除。

常見陷阱

  • 請勿假設每個世界模型都支援所有輸入類型。
  • 請確保簽章後的圖片或影片 URL 有足夠的有效期,以供服務進行重試抓取。
  • 在逾時後重試之前,請務必儲存回傳的任務 ID。
  • 若需要可下載的模型檔案,請使用 3D generation 而非可探索的世界。

API 參考

主題參考
建立世界建立世界
取得任務狀態取得任務狀態
取得世界狀態(相容性)取得世界狀態
準備媒體資產上傳準備媒體資產上傳
取得媒體資產取得媒體資產
列出世界列出世界
取得世界取得世界
刪除世界刪除 World
非同步作業Async Jobs
3D 生成指南3D Generation Guide

本頁內容