---
title: "Get World"
method: GET
path: "/marble/v1/worlds/{world_id}"
---

# Get World

`GET /marble/v1/worlds/{world_id}`

## Request

- Base URL: `https://api.worldlabs.ai`
- URL: `https://api.worldlabs.ai/marble/v1/worlds/{world_id}`
- Auth: API key in header `WLT-Api-Key`
- TypeScript: <https://skmtc.dev/worldlabs/apis/marble-public-api-v1/docs/marble/v1/worlds/:world_id/get.ts> (a function with typed inputs; its response is checked against the schema)

Get a world by ID.

Retrieves a world's details including generated assets if available.
Only the world owner or users with access to public worlds can retrieve them.

Args:
    world_id: The unique identifier of the world.

Returns:
    World object with world_id, display_name, tags, assets, created_at,
    updated_at, permission, model, world_prompt, and world_marble_url.

Raises:
    HTTPException: 404 if world not found or access denied

## Path parameters

- `world_id` string, required

## Response `200`

Successful Response

- World: A generated world, including asset URLs.
  - `assets` WorldAssets: Downloadable outputs of world generation.
    - `caption` string, nullable: AI-generated description of the world
    - `imagery` ImageryAssets: Imagery asset URLs.
      - `pano_url` string, nullable: Panorama image URL
    - `mesh` MeshAssets: Mesh asset URLs.
      - `collider_mesh_url` string, nullable: Collider mesh URL
      - `full_res_mesh_url` string, nullable: Full-resolution vertex-colored mesh URL
      - `hq_mesh_url` string, nullable: High-quality textured mesh URL
    - `splats` SplatAssets: Gaussian splat asset URLs.
      - `semantics_metadata` WorldSemanticsMetadata: Semantic metadata describing how to interpret the generated splat asset in real-world units. The exported asset is in arbitrary model units. Apply the transform below to convert to a metric, ground-aligned frame: metric_xyz = raw_xyz * metric_scale_factor aligned_xyz = metric_xyz - (0, ground_plane_offset, 0) Both fields are populated on every world generated by the current pipeline. They remain Optional only for backwards compatibility with worlds generated before December 2025, which predate metric-scale estimation. TODO: once pre-December-2025 worlds are migrated or aged out, tighten these fields to non-Optional and drop the `| None` from the type.
        - `ground_plane_offset` number, nullable: Vertical (Y-axis) offset, in meters, of the detected ground plane in the metric-scaled frame. Subtract from Y after applying `metric_scale_factor` to place the ground at y=0.
        - `metric_scale_factor` number, nullable: Multiplicative factor that converts raw asset coordinates to meters. Multiply all XYZ positions (and isotropic scales) by this value. A value of 1.0 means scale could not be inferred and the asset was left in model units.
      - `spz_urls` object, nullable: URLs for SPZ format Gaussian splat files
    - `thumbnail_url` string, nullable: Thumbnail URL for the world
  - `created_at` string, date-time, nullable: Creation timestamp
  - `display_name` string, required: Display name
  - `model` string, nullable: Model used for generation
  - `permission` Permission: Access control permissions for a resource.
    - `allow_id_access` boolean
    - `allowed_readers` string[]
    - `allowed_writers` string[]
    - `public` boolean
  - `tags` string[], nullable: Tags associated with the world
  - `updated_at` string, date-time, nullable: Last update timestamp
  - `world_id` string, required: World identifier
  - `world_marble_url` string, required: World Marble URL
  - `world_prompt` union: World prompt
    - WorldTextPromptOutput: Input prompt class for text-conditioned world generation.
      - `text_prompt` string, nullable
      - `type` 'text'
    - Prompt: For world models generating a world from a single image (+ text). Images can be generated using the :image-generation method. If no text prompt is provided, it will be generated via recaption.
      - `image_prompt` Content, required: Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB).
        - `data_base64` string, nullable
        - `extension` string, nullable: File extension without dot
        - `uri` string, nullable
      - `is_pano` boolean
      - `text_prompt` string, nullable
      - `type` 'image'
    - MultiImagePromptOutput: For world models supporting multi-image (+ text) input.
      - `multi_image_prompt` SphericallyLocatedContentOutput[], required
        - `azimuth` number, nullable
        - `data_base64` string, nullable
        - `extension` string, nullable: File extension without dot
        - `uri` string, nullable
      - `reconstruct_images` boolean
      - `text_prompt` string, nullable
      - `type` 'multi-image'
    - VideoPromptOutput: For world models supporting video (+ text) input.
      - `text_prompt` string, nullable
      - `type` 'video'
      - `video_prompt` Content, required: Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB).
        - `data_base64` string, nullable
        - `extension` string, nullable: File extension without dot
        - `uri` string, nullable
    - DepthPanoPrompt: For models conditioned on a depth pano and text. When depth_pano_image is a log-encoded PNG, z_min and z_max are required to decode it correctly. When it is an EXR file containing raw float depth values, z_min and z_max will both be ignored. Please set z_min and z_max both to None when using an EXR file.
      - `depth_pano_image` Content, required: Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB).
        - `data_base64` string, nullable
        - `extension` string, nullable: File extension without dot
        - `uri` string, nullable
      - `text_prompt` string, nullable
      - `type` 'depth-pano'
      - `z_max` number, nullable
      - `z_min` number, nullable
    - InpaintPanoPrompt: For models that inpaint the masked portion of a pano image.
      - `pano_image` Content, required: Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB).
        - `data_base64` string, nullable
        - `extension` string, nullable: File extension without dot
        - `uri` string, nullable
      - `pano_mask` Content, required: Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB).
        - `data_base64` string, nullable
        - `extension` string, nullable: File extension without dot
        - `uri` string, nullable
      - `text_prompt` string, nullable
      - `type` 'inpaint-pano'

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-03** `4a3ed614672e`: 1 info
  - added `depth-pano, image, inpaint-pano, multi-image, text, video` discriminator mapping keys to the `world_prompt/anyOf[subschema #1]/` response property for the response status `200`

[Operation history](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/changes/marble/v1/worlds/:world_id/get.md)

---

[API](https://skmtc.dev/worldlabs/apis/marble-public-api-v1.md) - [All operations](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/revisions/4a3ed614672e?raw)