Media Guides
Worlds
Create explorable Marble worlds from text, images, or video
Worlds creates a Marble environment that people can open and explore. If you need a downloadable object instead of an environment, use 3D generation.
Downloadable World files, such as splats, meshes and panorama images, are kept as automatic 30-day copies with TokenLab media-result URLs. The interactive World page and World records are not. See Data retention.
Inputs And Media Assets
A world can start from text, one or more images, or video, depending on the model. Find the Marble models (marble-*) in GET /v1/models?recommended_for=3d; their operation is world-generation. Send at least one input:
| Input | Field |
|---|---|
| Text | prompt, up to 4,000 characters |
| One image | image_url, or image as Base64 or a data URL; is_pano says whether it is already a panorama |
| Several images | images, up to 4 |
| Video | video_url |
| Advanced | world_prompt, a native prompt object that can reference an uploaded media asset |
Optional fields are display_name (up to 64 characters), seed, tags (up to 10), and permission. Reusable media can be uploaded once and referenced by its asset ID.
Access to media and world records is checked against the organization that owns the API key. Review the selected model’s permission options before sharing a world; a returned asset or viewer URL may have its own access rules.
Create And Poll
The create response contains a task ID and usually a poll_url. Keep the ID, then call GET /v1/tasks/{id} with it until the status is completed or failed. The Worlds poll_url points to /v1/worlds/generations/{id}, a compatibility path. Use /v1/tasks/{id} instead.
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"
}'Poll the task with the id from the create response:
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Manage Completed Worlds
Use POST /v1/worlds/list and GET /v1/worlds/{id} for completed worlds available in your account, and DELETE /v1/worlds/{id} to remove one. Use GET /v1/tasks/{id} for pending or failed generation tasks. Delete only when the user intentionally removes the generated world from your product.
Common Pitfalls
- Do not assume every world model supports every input type.
- Keep signed image or video URLs valid long enough for service fetch retries.
- Store the returned task ID before retrying after a timeout.
- Use 3D generation for downloadable model files rather than explorable worlds.
API Reference
| Topic | Reference |
|---|---|
| Create World | Create World |
| Get Task Status | Get Task Status |
| Get World Status (compatibility) | Get World Status |
| Prepare Media Asset Upload | Prepare Media Asset Upload |
| Get Media Asset | Get Media Asset |
| List Worlds | List Worlds |
| Get World | Get World |
| Delete World | Delete World |
| Async Jobs | Async Jobs |
| 3D Generation Guide | 3D Generation Guide |