> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Worlds

> Generate explorable worlds, upload media prompts, poll tasks, and manage completed worlds.

World generation creates explorable Marble worlds asynchronously. Use Worlds when the output is an environment users can open or revisit; use 3D generation when you need a standalone model asset.

## Inputs And Media Assets

World tasks can start from text, images, multiple images, or video depending on the selected model and request shape. For reusable media prompts, prepare a media asset first, then reference it in the world request. Media assets and completed worlds are available only to your account.

## Create And Poll

Create responses include a public task ID and usually a poll\_url. Store that ID before showing progress, then follow poll\_url or GET /v1/tasks/{id} until the task reaches completed or failed.

```bash theme={null}
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 Worlds

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 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](/api-reference/worlds/create-world)                             |
| Get World Status           | [Get World Status](/api-reference/worlds/get-world-status)                     |
| Prepare Media Asset Upload | [Prepare Media Asset Upload](/api-reference/worlds/prepare-media-asset-upload) |
| Get Media Asset            | [Get Media Asset](/api-reference/worlds/get-media-asset)                       |
| List Worlds                | [List Worlds](/api-reference/worlds/list-worlds)                               |
| Get World                  | [Get World](/api-reference/worlds/get-world)                                   |
| Delete World               | [Delete World](/api-reference/worlds/delete-world)                             |
| Async Jobs                 | [Async Jobs](/guides/async-jobs-polling)                                       |
| 3D Generation Guide        | [3D Generation Guide](/guides/3d-generation)                                   |