TokenLab

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:

InputField
Textprompt, up to 4,000 characters
One imageimage_url, or image as Base64 or a data URL; is_pano says whether it is already a panorama
Several imagesimages, up to 4
Videovideo_url
Advancedworld_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

TopicReference
Create WorldCreate World
Get Task StatusGet Task Status
Get World Status (compatibility)Get World Status
Prepare Media Asset UploadPrepare Media Asset Upload
Get Media AssetGet Media Asset
List WorldsList Worlds
Get WorldGet World
Delete WorldDelete World
Async JobsAsync Jobs
3D Generation Guide3D Generation Guide

On this page