媒體指南
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 |