Marble

https://docs.worldlabs.ai/
Admin
Marble is an AI-powered platform that creates high-fidelity, persistent 3D worlds from text prompts,...
Tokens:54,955
Snippets:667
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Verify skill installation

Source: https://docs.worldlabs.ai/api/agent-skill

Lists all skills exposed by the public mirror to confirm the installation.

```bash
npx skills add worldlabsai/marble-developer-api-skill --list
```

--------------------------------

### Worlds Generation Request Examples

Source: https://docs.worldlabs.ai/api/reference/openapi

Example payloads for generating worlds using text, image, or panoramic inputs.

```yaml
display_name: Coastal Castle
model: marble-1.0
permission:
  public: false
seed: 42
tags:
- fantasy
- coastal
world_prompt:
  text_prompt: A grand, ivy-covered castle rises from the shoreline at sunset,
    its reflection shimmering in the tranquil ocean waves.
  type: text
```

```yaml
display_name: Greenhouse Workshop
model: marble-1.0-draft
world_prompt:
  image_prompt:
    source: uri
    uri: https://example.com/my-image.jpg
  text_prompt: A peaceful, sunlit greenhouse workshop filled with plants and
    glassware, where soft light filters through cracked windows and ivy creeps
    along the walls.
  type: image
```

```yaml
display_name: World from an Existing Pano
model: marble-1.1
world_prompt:
  image_prompt:
    source: uri
    uri: https://example.com/my-equirect-pano.jpg
  is_pano: auto
  type: image
```

```yaml
permission:
  public: true
```

--------------------------------

### Insufficient Credits Error Example

Source: https://docs.worldlabs.ai/api/reference/openapi

Example response body for a 402 error when an account lacks sufficient API credits.

```json
{
  "detail": "Insufficient API credits to start this request. Add credits
    or enable auto-refill at https://platform.worldlabs.ai/billing."
}
```

--------------------------------

### Install the World Labs API skill

Source: https://docs.worldlabs.ai/api/agent-skill

Adds the World Labs API skill to the current project.

```bash
npx skills add worldlabsai/marble-developer-api-skill --skill marble-developer-api
```

--------------------------------

### PanoDepthToRgbRequest Example Payloads

Source: https://docs.worldlabs.ai/api/reference/openapi

Example JSON payloads for the PanoDepthToRgbRequest schema, demonstrating usage with EXR and PNG depth map inputs.

```json
depth_pano_image:
    source: uri
    uri: https://example.com/depth.exr
  text_prompt: The scene is a warm, rustic cabin interior with a realistic style
    and a cozy winter atmosphere. Wooden walls and exposed beams frame the room,
    while a stone fireplace casts soft amber light across simple furnishings
    and natural textures. The 360 scene is faultless.
```

```json
depth_pano_image:
    source: uri
    uri: https://example.com/greenhouse-depth.exr
  text_prompt: A peaceful greenhouse workshop filled with plants and glassware,
    with soft sunlight, weathered wood, and ivy creeping along the walls.
```

```json
depth_pano_image:
    source: uri
    uri: https://example.com/depth.png
  text_prompt: The scene is a warm Mediterranean kitchen rendered in a realistic
    style with a bright, welcoming coastal atmosphere. The overall tone is relaxed
    and sunlit, combining natural materials with crisp handcrafted details.
    Blue ceramic tiles wrap the backsplash and continue across key architectural
    surfaces, giving the room a cool accent against creamy plaster walls. Wooden
    cabinetry lines the perimeter in a balanced arrangement, with paneled doors,
    open shelving, and brass hardware contributing to the room's refined but
    lived-in character. A broad countertop of pale stone runs between the cabinets,
    creating a continuous work surface that anchors the cooking area. A central
    table with a solid wood top occupies the middle of the room, surrounded
    by simple chairs and small ceramic vessels that reinforce the artisanal
    style. Arched openings connect the kitchen to adjacent areas, while French
    doors admit generous daylight and suggest an outdoor terrace nearby. Terracotta
    accents, woven textures, and neatly arranged cookware add visual richness
    without cluttering the space. The cabinetry, tiled surfaces, and stone counters
    form a coherent ring around the room, while the table remains the central
    focal element within the composition. The 360 scene is faultless.
  z_max: 100.0
  z_min: 0.1
```

--------------------------------

### ListWorldsRequest Examples

Source: https://docs.worldlabs.ai/api/reference/openapi

Various request configurations for filtering and paginating world lists.

```yaml
- model: marble-1.0
  page_size: 20
  sort_by: created_at
  status: SUCCEEDED
```

```yaml
- page_size: 50
  sort_by: created_at
  status: SUCCEEDED
  tags:
  - fantasy
  - nature
```

```yaml
- created_after: '2024-01-01T00:00:00Z'
  created_before: '2024-12-31T23:59:59Z'
  page_size: 100
  sort_by: created_at
```

```yaml
- model: marble-1.0-draft
  page_size: 30
  tags:
  - landscape
```

```yaml
- page_size: 20
  page_token: eyJzbmFwc2hvdF90aW1lIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI0LTAxLTAxVDAwOjAwOjAwWiIsImxhc3RfaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ==
  sort_by: created_at
```

--------------------------------

### Media Asset Preparation Response

Source: https://docs.worldlabs.ai/api

Example of the JSON response containing the media asset ID and the signed upload URL details.

```json
{
  "media_asset": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_name": "my-video.mp4",
    "kind": "video",
    "extension": "mp4",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": null,
    "metadata": null
  },
  "upload_info": {
    "upload_url": "<signed_upload_url>",
    "upload_method": "PUT",
    "required_headers": {
      "x-goog-content-length-range": "0,1048576000"
    }
  }
}
```

--------------------------------

### Invoke the skill in a coding agent

Source: https://docs.worldlabs.ai/api/agent-skill

Examples of prompts to use when invoking the skill for specific tasks.

```text
Use the marble-developer-api skill to build a TypeScript client for World API v1.
```

```text
Use the marble-developer-api skill to upload an image, generate a world, and poll the operation.
```

--------------------------------

### World object response structure

Source: https://docs.worldlabs.ai/api

Example JSON response containing world metadata, asset URLs, and generation parameters.

```json
{
  "world": {
    "id": "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
    "display_name": "Mystical Forest",
    "tags": null,
    "world_marble_url": "https://marble.worldlabs.ai/world/dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
    "assets": {
      "caption": "The scene is a fantastical forest...",
      "thumbnail_url": "<thumbnail_url>",
      "splats": {
        "spz_urls": {
          "500k": "<500k_spz_url>",
          "full_res": "<full_res_spz_url>",
          "100k": "<100k_spz_url>"
        },
        "semantics_metadata": {
          "metric_scale_factor": 1.23,
          "ground_plane_offset": 0.42
        }
      },
      "mesh": {
        "collider_mesh_url": "<collider_mesh_url>"
      },
      "imagery": {
        "pano_url": "<pano_url>"
      }
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:00Z",
    "permission": null,
    "world_prompt": {
      "type": "text",
      "text_prompt": "The scene is a fantastical forest..."
    },
    "model": "marble-1.1"
  }
}
```

--------------------------------

### Get Operation OpenAPI Specification

Source: https://docs.worldlabs.ai/api/reference/operations/get

Defines the GET endpoint for retrieving operation status and the associated response schema.

```yaml
openapi: 3.1.0
info:
  description: Public-facing API for the Marble platform
  summary: Marble Public API v1
  title: Marble Public API v1
  version: 1.0.0
servers:
  - description: World API
    url: https://api.worldlabs.ai
security:
  - ApiKeyAuth: []
paths:
  /marble/v1/operations/{operation_id}:
    get:
      summary: Get Operation
      description: |-
        Get an operation by ID.

        Poll this endpoint to check the status of a long-running operation.
        When done=true, the response field contains the generated world.

        Args:
            operation_id: The operation identifier from /worlds:generate.

        Returns:
            GetOperationResponse[World] with:
                - operation_id: Operation identifier
                - created_at: Creation timestamp
                - updated_at: Last update timestamp
                - expires_at: Expiration timestamp
                - done: true when complete, false while in progress
                - error: Error details if failed, null otherwise
                - metadata: Progress information and world_id
                - response: Generated World if done=true, null otherwise
                - cost: Settled credit cost breakdown; populated only when the
                  operation completed successfully (done=true with no error)
                  and a public price is known for its operation type. Failed
                  or in-progress operations return null.

        Raises:
            HTTPException: 401 if unauthorized
            HTTPException: 404 if operation not found
            HTTPException: 500 if request fails
      operationId: get_operation_marble_v1_operations__operation_id__get
      parameters:
        - in: path
          name: operation_id
          required: true
          schema:
            title: Operation Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/GetOperationResponse_Union_World__PanoDepthToRgbResult__ExportWorldResult__
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    GetOperationResponse_Union_World__PanoDepthToRgbResult__ExportWorldResult__:
      properties:
        cost:
          anyOf:
            - $ref: '#/components/schemas/OperationCost'
            - type: 'null'
          description: >-
            Settled credit cost for the operation. Populated only on successful
            completion.
        created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Creation timestamp
          title: Created At
        done:
          description: True if the operation is completed
          title: Done
          type: boolean
        error:
          anyOf:
            - $ref: '#/components/schemas/OperationError'
            - type: 'null'
          description: Error information if the operation failed
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Expiration timestamp
          title: Expires At
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Service-specific metadata, such as progress percentage
          title: Metadata
```

--------------------------------

### OpenAPI Specification for Get Credits

Source: https://docs.worldlabs.ai/api/reference/credits/get

Defines the GET /marble/v1/credits endpoint, including security requirements and the CreditsResponse schema.

```yaml
openapi: 3.1.0
info:
  description: Public-facing API for the Marble platform
  summary: Marble Public API v1
  title: Marble Public API v1
  version: 1.0.0
servers:
  - description: World API
    url: https://api.worldlabs.ai
security:
  - ApiKeyAuth: []
paths:
  /marble/v1/credits:
    get:
      tags:
        - credits
      summary: Get Credits
      description: |-
        Get remaining API credits for the authenticated user.

        Returns:
            CreditsResponse with the current aggregate API credit balance.

        Raises:
            HTTPException: 404 if the caller is not an API-enabled user
            HTTPException: 503 if the billing backend is unavailable
      operationId: get_credits_marble_v1_credits_get
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditsResponse'
          description: Successful Response
components:
  schemas:
    CreditsResponse:
      description: Remaining credits for the authenticated API user.
      properties:
        remaining_credits:
          description: Remaining API credits available to the authenticated user.
          minimum: 0
          title: Remaining Credits
          type: number
      required:
        - remaining_credits
      title: CreditsResponse
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key for authentication. Get your key from the developer portal.
      in: header
      name: WLT-Api-Key
      type: apiKey
```

--------------------------------

### Prepare Media Asset Upload

Source: https://docs.worldlabs.ai/api

Requests a signed upload URL for a local file by specifying the file name, kind, and extension.

```bash
curl -X POST 'https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload' \
  -H 'Content-Type: application/json' \
  -H 'WLT-Api-Key: YOUR_API_KEY' \
  -d '{
    "file_name": "my-video.mp4",
    "kind": "video",
    "extension": "mp4"
  }'
```

```javascript
const response = await fetch('https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'WLT-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    file_name: 'my-video.mp4',
    kind: 'video',
    extension: 'mp4'
  })
});

const data = await response.json();
console.log(data);
```

```python
import requests

url = "https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload"

payload = {
    "file_name": "my-video.mp4",
    "kind": "video",
    "extension": "mp4"
}
headers = {
    "WLT-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

--------------------------------

### Install the World Labs API skill globally

Source: https://docs.worldlabs.ai/api/agent-skill

Adds the World Labs API skill globally for use across multiple projects.

```bash
npx skills add worldlabsai/marble-developer-api-skill --skill marble-developer-api --global
```

--------------------------------

### Prepare a local file for upload

Source: https://docs.worldlabs.ai/api

Requests a signed upload URL for a local file before it can be used in a generation request.

```bash
curl -X POST 'https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload' \
  -H 'Content-Type: application/json' \
  -H 'WLT-Api-Key: YOUR_API_KEY' \
  -d '{
    "file_name": "my-image.jpg",
    "kind": "image",
    "extension": "jpg"
  }'
```

```javascript
const response = await fetch('https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'WLT-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    file_name: 'my-image.jpg',
    kind: 'image',
    extension: 'jpg'
  })
});

const data = await response.json();
console.log(data);
```

```python
import requests

url = "https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload"
```

--------------------------------

### POST /marble/v1/media-assets:prepare_upload

Source: https://docs.worldlabs.ai/api

Prepares a media asset for upload by generating a signed URL.

```APIDOC
## POST /marble/v1/media-assets:prepare_upload

### Description
This endpoint initiates the upload process for a media file by returning a signed upload URL and required headers.

### Method
POST

### Endpoint
https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload

### Request Body
- **file_name** (string) - Required - The name of the file being uploaded.
- **kind** (string) - Required - The type of media (e.g., "video").
- **extension** (string) - Required - The file extension (e.g., "mp4").

### Response
#### Success Response (200)
- **media_asset** (object) - Details of the created media asset.
- **upload_info** (object) - Information required to perform the file upload, including the signed URL and headers.
```

--------------------------------

### Get World OpenAPI Specification

Source: https://docs.worldlabs.ai/api/reference/worlds/get

Defines the GET endpoint for retrieving world details, including path parameters and the World schema definition.

```yaml
openapi: 3.1.0
info:
  description: Public-facing API for the Marble platform
  summary: Marble Public API v1
  title: Marble Public API v1
  version: 1.0.0
servers:
  - description: World API
    url: https://api.worldlabs.ai
security:
  - ApiKeyAuth: []
paths:
  /marble/v1/worlds/{world_id}:
    get:
      summary: Get World
      description: >-
        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
      operationId: get_world_marble_v1_worlds__world_id__get
      parameters:
        - in: path
          name: world_id
          required: true
          schema:
            title: World Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/World'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    World:
      description: A generated world, including asset URLs.
      properties:
        assets:
          anyOf:
            - $ref: '#/components/schemas/WorldAssets'
            - type: 'null'
          description: Generated world assets
        created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Creation timestamp
          title: Created At
        display_name:
          description: Display name
          title: Display Name
          type: string
        model:
          anyOf:
            - type: string
            - type: 'null'
          description: Model used for generation
          title: Model
        permission:
          anyOf:
            - $ref: '#/components/schemas/Permission'
            - type: 'null'
          description: Access control permissions for the world
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Tags associated with the world
          title: Tags
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Last update timestamp
          title: Updated At
        world_id:
          description: World identifier
          title: World Id
          type: string
        world_marble_url:
          description: World Marble URL
          title: World Marble Url
          type: string
        world_prompt:
          anyOf:
            - discriminator:
                mapping:
                  depth-pano:
                    $ref: '#/components/schemas/DepthPanoPrompt'
                  image:
                    $ref: '#/components/schemas/Prompt'
                  inpaint-pano:
                    $ref: '#/components/schemas/InpaintPanoPrompt'
                  multi-image:
                    $ref: '#/components/schemas/MultiImagePrompt-Output'
                  text:
                    $ref: '#/components/schemas/WorldTextPrompt-Output'
                  video:
                    $ref: '#/components/schemas/VideoPrompt-Output'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/WorldTextPrompt-Output'
                - $ref: '#/components/schemas/Prompt'
                - $ref: '#/components/schemas/MultiImagePrompt-Output'
                - $ref: '#/components/schemas/VideoPrompt-Output'
                - $ref: '#/components/schemas/DepthPanoPrompt'
                - $ref: '#/components/schemas/InpaintPanoPrompt'
            - type: 'null'
          description: World prompt
          title: World Prompt
      required:
        - world_id
```

--------------------------------

### Invalid JSON Request Body Example

Source: https://docs.worldlabs.ai/api/errors

An example of an incorrectly formatted request body that lacks proper JSON serialization, such as unquoted keys and incorrect assignment operators.

```text
{model=marble-1.0, permission={allow_id_access=false, public=false}, world_prompt={...}}
```

--------------------------------

### Get Media Asset by ID (OpenAPI)

Source: https://docs.worldlabs.ai/api/reference/media-assets/get

This OpenAPI definition describes the GET request to retrieve a media asset. It specifies the endpoint, parameters, and possible responses, including success and validation errors.

```yaml
GET /marble/v1/media-assets/{media_asset_id}
openapi: 3.1.0
info:
  description: Public-facing API for the Marble platform
  summary: Marble Public API v1
  title: Marble Public API v1
  version: 1.0.0
servers:
  - description: World API
    url: https://api.worldlabs.ai
security:
  - ApiKeyAuth: []
paths:
  /marble/v1/media-assets/{media_asset_id}:
    get:
      summary: Get Media Asset
      description: |-
        Get a media asset by ID.

        Retrieves metadata for a previously created media asset.

        Args:
            media_asset_id: The media asset identifier.

        Returns:
            MediaAsset object with media_asset_id, file_name, extension, kind,
            metadata, created_at, and updated_at.

        Raises:
            HTTPException: 404 if not found
      operationId: get_media_asset_marble_v1_media_assets__media_asset_id__get
      parameters:
        - in: path
          name: media_asset_id
          required: true
          schema:
            title: Media Asset Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaAsset'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    MediaAsset:
      description: |-
        A user-uploaded media asset stored in managed storage.

        MediaAssets can be images, videos, or binary blobs that are used
        as input to world generation.
      properties:
        created_at:
          description: Creation timestamp
          format: date-time
          title: Created At
          type: string
        extension:
          anyOf:
            - type: string
            - type: 'null'
          description: File extension without dot
          examples:
            - mp4
            - png
            - jpg
          title: Extension
        file_name:
          description: File name
          title: File Name
          type: string
        kind:
          $ref: '#/components/schemas/MediaAssetKind'
          description: High-level media type
          examples:
            - image
            - video
        media_asset_id:
          description: Server-generated media asset identifier
          title: Media Asset Id
          type: string
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Optional application-specific metadata
          title: Metadata
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Last update timestamp
          title: Updated At
      required:
        - media_asset_id
        - file_name
        - kind
        - created_at
      title: MediaAsset
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    MediaAssetKind:
      description: High-level media asset type.
      enum:
        - image
        - video
      title: MediaAssetKind
      type: string
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key for authentication. Get your key from the developer portal.
      in: header
      name: WLT-Api-Key
      type: apiKey

```

--------------------------------

### POST /marble/v1/media_assets/prepare_upload

Source: https://docs.worldlabs.ai/api/reference/openapi#world-api-v1-openapi-spec

Prepares a media asset for upload by returning an upload URL and required headers.

```APIDOC
## POST /marble/v1/media_assets/prepare_upload

### Description
Prepares a media asset for upload. Returns a media_asset_id to be used in world generation and upload instructions.

### Method
POST

### Endpoint
/marble/v1/media_assets/prepare_upload

### Parameters
#### Request Body
- **file_name** (string) - Required - Your file's name (e.g., "landscape.jpg")
- **extension** (string) - Required - File extension without dot (e.g., "jpg", "png", "mp4")
- **kind** (string) - Required - Either "image" or "video"
- **metadata** (object) - Optional - Custom metadata object

### Response
#### Success Response (200)
- **media_asset** (object) - Object with media_asset_id
- **upload_info** (object) - Object with upload_url, required_headers, and curl_example
```

--------------------------------

### GET /operations/{operation_id}

Source: https://docs.worldlabs.ai/api/reference/openapi

Retrieves the status and result of a long-running operation.

```APIDOC
## GET /operations/{operation_id}

### Description
Retrieves the status and result of a long-running operation by its ID.

### Method
GET

### Endpoint
/operations/{operation_id}

### Parameters
#### Path Parameters
- **operation_id** (string) - Required - The unique identifier of the operation.
```

--------------------------------

### POST /marble/v1/media-assets:prepare_upload

Source: https://docs.worldlabs.ai/api

Prepares a local file for upload by generating a signed upload URL.

```APIDOC
## POST /marble/v1/media-assets:prepare_upload

### Description
Initiates the upload process for a local file by requesting a signed upload URL from the server.

### Method
POST

### Endpoint
https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload

### Request Body
- **file_name** (string) - Required - The name of the file.
- **kind** (string) - Required - The type of media (e.g., 'image').
- **extension** (string) - Required - The file extension (e.g., 'jpg').

### Request Example
{
  "file_name": "my-image.jpg",
  "kind": "image",
  "extension": "jpg"
}
```

--------------------------------

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

Source: https://docs.worldlabs.ai/api/reference/openapi#world-api-v1-openapi-spec

Retrieves details for a specific world by its ID.

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

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

### Method
GET

### Endpoint
/marble/v1/worlds/{world_id}

### Parameters
#### Path Parameters
- **world_id** (string) - Required - The unique identifier of the world.

### Response
#### Success Response (200)
- **world_id** (string) - Unique identifier
- **display_name** (string) - Name of the world
- **tags** (array) - Associated tags
- **assets** (object) - Generated assets
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp
- **permission** (string) - Access level
- **model** (string) - Model used
- **world_prompt** (string) - Generation prompt
- **world_marble_url** (string) - URL to the marble asset
```

--------------------------------

### POST /marble/v1/media-assets:prepare_upload

Source: https://docs.worldlabs.ai/api/reference/media-assets/prepare-upload

Prepares a media asset upload by creating a record and returning a signed upload URL. This is the first step in uploading images or videos for use in world generation.

```APIDOC
## POST /marble/v1/media-assets:prepare_upload

### Description
Prepare a media asset upload for use in world generation. This API endpoint creates a media asset record and returns a signed upload URL. Use this workflow to upload images or videos that you want to reference in world generation requests.

### Method
POST

### Endpoint
/marble/v1/media-assets:prepare_upload

### Parameters
#### Request Body
- **file_name** (string) - Required - Your file's name (e.g., "landscape.jpg")
- **kind** (string) - Required - Either "image" or "video"
- **extension** (string) - Optional - File extension without dot (e.g., "jpg", "png", "mp4")
- **metadata** (object) - Optional - Optional custom metadata object

### Response
#### Success Response (200)
- **media_asset** (object) - Object with `media_asset_id` (use this in world generation)
  - **media_asset_id** (string) - The ID of the media asset.
- **upload_info** (object) - Object with `upload_url`, `required_headers`, and `curl_example`
  - **upload_url** (string) - The signed URL for uploading the file.
  - **required_headers** (object) - Key-value pairs of headers required for the upload.
  - **curl_example** (string) - An example curl command for uploading the file.

#### Response Example
{
  "media_asset": {
    "media_asset_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  },
  "upload_info": {
    "upload_url": "https://example.com/upload/signed-url",
    "required_headers": {
      "Content-Type": "image/png",
      "Authorization": "Bearer YOUR_TOKEN"
    },
    "curl_example": "curl --request PUT --url https://example.com/upload/signed-url --header \"Content-Type: image/png\" --header \"Authorization: Bearer YOUR_TOKEN\" --upload-file /path/to/your/file"
  }
}

#### Error Response (422)
- **detail** (array) - Details about the validation error.
```

--------------------------------

### GET /marble/v1/credits

Source: https://docs.worldlabs.ai/api/reference/credits/get

Retrieves the remaining API credits for the authenticated user.

```APIDOC
## GET /marble/v1/credits

### Description
Get remaining API credits for the authenticated user.

### Method
GET

### Endpoint
/marble/v1/credits

### Response
#### Success Response (200)
- **remaining_credits** (number) - Remaining API credits available to the authenticated user.

#### Response Example
{
  "remaining_credits": 1000
}
```

--------------------------------

### GET /worlds

Source: https://docs.worldlabs.ai/api/reference/worlds/list

Retrieves a paginated list of worlds based on optional filters.

```APIDOC
## GET /worlds

### Description
Retrieves a list of API-generated worlds. Supports filtering, sorting, and pagination.

### Method
GET

### Endpoint
/worlds

### Parameters
#### Query Parameters
- **model** (string) - Optional - Filter by model used for generation.
- **page_size** (integer) - Optional - Number of results per page (1-100). Default: 20.
- **page_token** (string) - Optional - Cursor token for pagination.
- **sort_by** (string) - Optional - Sort results by 'created_at' or 'updated_at'. Default: 'created_at'.
- **status** (string) - Optional - Filter by world status (SUCCEEDED, PENDING, FAILED, RUNNING).
- **tags** (array) - Optional - Filter by tags (returns worlds with ANY of these tags).

### Response
#### Success Response (200)
- **worlds** (array) - List of worlds.
- **next_page_token** (string) - Token for fetching the next page of results.
```

--------------------------------

### POST /marble/v1/media-assets:prepare_upload

Source: https://docs.worldlabs.ai/api

Prepares an upload for a media asset, returning the necessary upload URL and headers.

```APIDOC
## POST /marble/v1/media-assets:prepare_upload

### Description
Prepares an upload for a media asset, returning the necessary upload URL and headers.

### Method
POST

### Endpoint
https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload

### Request Body
- **file_name** (string) - Required - The name of the file.
- **kind** (string) - Required - The type of media (e.g., 'image').
- **extension** (string) - Required - The file extension (e.g., 'jpg').

### Response
#### Success Response (200)
- **media_asset** (object) - Contains the media_asset id.
- **upload_info** (object) - Contains the upload_url and required_headers.
```

--------------------------------

### Register a media asset

Source: https://docs.worldlabs.ai/api

Initializes a media asset record to obtain a signed upload URL.

```python
payload = {
    "file_name": "my-image.jpg",
    "kind": "image",
    "extension": "jpg"
}
headers = {
    "WLT-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

--------------------------------

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

Source: https://docs.worldlabs.ai/api/reference/worlds

Retrieves details for a specific world, including asset URLs.

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

### Description
Retrieve a world, including generated asset URLs when they are available.

### Method
GET

### Endpoint
/marble/v1/worlds/{world_id}

### Parameters
#### Path Parameters
- **world_id** (string) - Required - The unique identifier of the world.
```

--------------------------------

### POST /marble/v1/media-assets:prepare_upload

Source: https://docs.worldlabs.ai/api

Prepares an upload for a media asset, returning an upload URL and necessary headers for the file transfer.

```APIDOC
## POST /marble/v1/media-assets:prepare_upload

### Description
Prepares an upload for a media asset, returning an upload URL and necessary headers for the file transfer.

### Method
POST

### Endpoint
https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload

### Request Body
- **file_name** (string) - Required - The name of the file being uploaded.
- **kind** (string) - Required - The type of media asset (e.g., "image").
- **extension** (string) - Required - The file extension (e.g., "jpg").

### Response
#### Success Response (200)
- **media_asset** (object) - The created media asset object.
- **upload_info** (object) - Contains the upload_url and required_headers for the file upload.
```
Tokens:
Raw