Worlds

Worlds creates a Marble environment that people can open and explore. If you need a downloadable object instead of an environment, use 3D generation.

World records and assets are not covered by the automatic 30-day HTTP(S) generated-media copy retention. See Data retention.

Inputs And Media AssetsCopy Anchor Link

A world can start from text, one or more images, or video, depending on the model. 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 PollCopy Anchor Link

The create response contains a task ID and usually a poll_url. Keep the ID, then query poll_url or GET /v1/tasks/{id} until the status is completed or failed.

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"
  }'

Manage Completed WorldsCopy Anchor Link

Use the Worlds list and get endpoints for completed worlds available in your account. Use task status endpoints for pending or failed generation tasks. Delete only when the user intentionally removes the generated world from your product.

Common PitfallsCopy Anchor Link

• 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 ReferenceCopy Anchor Link