### Initiate World Generation Operation

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

Use this Python snippet to start a new world generation operation. Replace 'YOUR_API_KEY' with your actual API key. The response will indicate if the operation is complete.

```python
import requests

url = "https://api.worldlabs.ai/marble/v1/operations/20bffbb1-4ba7-453f-a116-93eaw1a6843e"

headers = {
    "WLT-Api-Key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)

print(response.text)
```

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

### Example World Generation Request with Media Asset

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

After uploading a media asset, use its media_asset_id in a world generation request. Ensure the source type is set to 'media_asset'.

```json
{
  "world_prompt": {
    "type": "image",
    "image_prompt":
      {
      "source": "media_asset",
      "media_asset_id": "<your-media-asset-id>"
      }
  }
}
```

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

### Prepare Media Asset Upload (Bash)

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

Call this endpoint to obtain a signed URL for uploading a media asset. Specify 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"
  }'
```

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

### 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

```

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

### Get Media Asset

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

Retrieves metadata for a specific media asset using its unique identifier.

```APIDOC
## GET /marble/v1/media-assets/{media_asset_id}

### 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

### Method
GET

### Endpoint
/marble/v1/media-assets/{media_asset_id}

#### Path Parameters
- **media_asset_id** (string) - Required - The media asset identifier.
```

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

### Prepare Media Asset Upload (Python)

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

Call this endpoint to obtain a signed URL for uploading a media asset. Specify the file name, kind, and extension.

```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)
```

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

### Prepare Media Asset Upload

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

Prepare to upload a local file by obtaining a signed URL. This involves making a POST request with file details. The response provides the upload URL and required headers.

```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"

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 Latest World Data

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

Retrieves the latest version of the world data. Requires authentication with a WLT-Api-Key.

```APIDOC
## GET /worlds

### Description
Retrieves the latest version of the world data.

### Method
GET

### Endpoint
/worlds

### Request Headers
- **WLT-Api-Key** (string) - Required - Your API key for authentication.

### Response
#### Success Response (200)
- **world** (object) - Contains detailed information about the world.
  - **id** (string) - The unique identifier for the world.
  - **display_name** (string) - The display name of the world.
  - **tags** (array | null) - Tags associated with the world.
  - **world_marble_url** (string) - URL to the world's marble representation.
  - **assets** (object) - Contains various assets related to the world.
    - **caption** (string) - AI-generated description of the world.
    - **thumbnail_url** (string) - URL to the world's thumbnail image.
    - **splats** (object) - Contains 3D Gaussian splat files.
      - **spz_urls** (object)
        - **500k** (string) - URL for the 500k resolution SPZ file.
        - **full_res** (string) - URL for the full resolution SPZ file.
        - **100k** (string) - URL for the 100k resolution SPZ file.
    - **mesh** (object) - Contains mesh data.
      - **collider_mesh_url** (string) - URL to the collider mesh file.
    - **imagery** (object) - Contains imagery data.
      - **pano_url** (string) - URL to the panorama image.
  - **created_at** (string) - Timestamp when the world was created.
  - **updated_at** (string) - Timestamp when the world was last updated.
  - **permission** (null) - Placeholder for permission information.
  - **world_prompt** (object) - The prompt used to generate the world.
    - **type** (string) - Type of prompt (e.g., 'text').
    - **text_prompt** (string) - The text prompt used.
  - **model** (string) - The model used for generation.

### Response Example
```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>"
        }
      },
      "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 Response Schema

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

Response schema for an ongoing or completed operation, including status and results.

```APIDOC
## GetOperationResponse[World]

### Description
Response for an operation, indicating its status and potential results.

### Properties
- **operation_id** (string, required) - Operation identifier.
- **done** (boolean, required) - Whether the operation has completed.
- **error** (object, optional) - Error information if the operation failed.
- **expires_at** (string, format: date-time, optional) - Expiration timestamp of the operation.
- **metadata** (object, optional) - Service-specific metadata, such as progress percentage.
- **response** (object, optional) - Result payload when done=true and no error. Structure depends on operation type.
```

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

### Prepare Media Asset Upload

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

Use this endpoint to prepare for uploading a local image file. It requires the file name, kind, and extension. The response contains a URL to upload the file to.

```bash
# Prepare upload for first image
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": "front.jpg",
    "kind": "image",
    "extension": "jpg"
  }'

# Upload the file to the returned upload_url
curl -X PUT '<upload_url>'
```

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

### Get Operation by ID

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

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

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

### Description
Get an operation by ID.

### Method
GET

### Endpoint
/operations/{operation_id}

### Parameters
#### Path Parameters
- **operation_id** (string) - Required - The operation identifier from /worlds:generate.

### Response
#### Success Response (200)
- **operation_id** (string) - Operation identifier
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp
- **expires_at** (string) - Expiration timestamp
- **done** (boolean) - true when complete, false while in progress
- **error** (object | null) - Error details if failed, null otherwise
- **metadata** (object) - Progress information and world_id
- **response** (object | null) - Generated World if done=true, null otherwise

#### Response Example
{
  "operation_id": "op_12345",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:05:00Z",
  "expires_at": "2023-10-27T11:00:00Z",
  "done": true,
  "error": null,
  "metadata": {
    "progress": 100,
    "world_id": "world_abcde"
  },
  "response": {
    "world_data": "..."
  }
}

### Error Handling
- **401** - Unauthorized
- **404** - Operation not found
- **500** - Request failed
```

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

### Prepare Media Asset Upload (JavaScript)

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

Call this endpoint to obtain a signed URL for uploading a media asset. Specify the file name, kind, and extension.

```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);
```

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

### Get World

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

Retrieves the details of a specific world by its unique identifier. Access is restricted to the world owner or users with permissions for public worlds.

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

### 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.

### 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) - The unique identifier of the world.
- **display_name** (string) - The display name of the world.
- **tags** (array) - Tags associated with the world.
- **assets** (object) - World assets.
- **created_at** (string) - Creation timestamp.
- **updated_at** (string) - Last update timestamp.
- **permission** (string) - Permission level of the world.
- **model** (string) - The model used for world generation.
- **world_prompt** (string) - The prompt used for world generation.
- **world_marble_url** (string) - The URL to the world's marble asset.

### Raises
- HTTPException: 404 if world not found or access denied
```

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

### 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.
```

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

### Prepare Media Asset Upload

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

Prepares for a media asset upload by creating a record and providing a signed upload URL. This is the first step in uploading images or videos for 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.

## Workflow

1. **Prepare Upload** (this endpoint): Get a `media_asset_id` and `upload_url`
2. **Upload File**: Use the signed URL to upload your file
3. **Generate World**: Reference the `media_asset_id` in `/worlds:generate` with source type "media_asset"

## Request Parameters

- `file_name`: Your file's name (e.g., "landscape.jpg")
- `extension`: File extension without dot (e.g., "jpg", "png", "mp4")
- `kind`: Either "image" or "video"
- `metadata`: Optional custom metadata object

## Response

Returns a `MediaAssetPrepareUploadResponse` containing:

- `media_asset`: Object with `media_asset_id` (use this in world generation)
- `upload_info`: Object with `upload_url`, `required_headers`, and `curl_example`

## Uploading Your File

Use the returned `upload_url` and `required_headers` to upload your file:

```bash
curl --request PUT \
  --url <upload_url> \
  --header "Content-Type: <content-type>" \
  --header "<header-name>: <header-value>" \
  --upload-file /path/to/your/file
```

Replace:
- `<upload_url>`: The `upload_url` from the response
- `<content-type>`: MIME type (e.g., `image/png`, `image/jpeg`, `video/mp4`)
- `<header-name>: <header-value>`: Each header from `required_headers`
- `/path/to/your/file`: Path to your local file

## Example Usage in World Generation

After uploading, use the `media_asset_id` in a world generation request:

```json
{
  "world_prompt": {
    "type": "image",
    "image_prompt": {
      "source": "media_asset",
      "media_asset_id": "<your-media-asset-id>"
    }
  }
}
```

### Method
POST

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

#### 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 - Optional custom metadata object

### Response
#### Success Response (200)
- `media_asset` (object) - Object with `media_asset_id` (use this in world generation)
- `upload_info` (object) - Object with `upload_url`, `required_headers`, and `curl_example`
```

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

### Get Operation

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

Retrieves the status of a long-running operation, such as world generation. Once the operation is complete (done=true), the response field will contain the generated world.

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

### 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.

### Method
GET

### Endpoint
/operations/{operation_id}

### Parameters
#### Path Parameters
- **operation_id** (string) - Required - The operation identifier from /worlds:generate.

### Response
#### Success Response (200)
- **operation_id** (string) - Operation identifier
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp
- **expires_at** (string) - Expiration timestamp
- **done** (boolean) - true when complete, false while in progress
- **error** (object | null) - Error details if failed, null otherwise
- **metadata** (object) - Progress information and world_id
- **response** (object | null) - Generated World if done=true, null otherwise

### Raises
- HTTPException: 401 if unauthorized
- HTTPException: 404 if operation not found
- HTTPException: 500 if request fails
```

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

### Generate World

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

Starts a new world generation job. Poll the /operations/{operation_id} endpoint to check status and retrieve the generated world.

```APIDOC
## POST /marble/v1/worlds:generate

### Description
Starts world generation. Creates a new world generation job and returns a long-running operation. Poll the /operations/{operation_id} endpoint to check generation status and retrieve the generated world when complete.

### Method
POST

### Endpoint
/marble/v1/worlds:generate

### Parameters
#### Request Body
- **request** (WorldsGenerateRequest) - Required - The world generation request containing world_prompt, display_name, tags, model, seed, and permission settings.

### Request Example
```json
{
  "display_name": "Enchanted Forest",
  "model": "marble-1.0",
  "permission": {
    "public": false
  },
  "seed": 42,
  "tags": [
    "fantasy",
    "nature"
  ],
  "world_prompt": {
    "text_prompt": "A mystical forest with glowing mushrooms",
    "type": "text"
  }
}
```

### Response
#### Success Response (200)
- **operation_id** (string) - The ID of the long-running operation.
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.

#### Response Example
```json
{
  "operation_id": "op_abc123xyz",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z"
}
```

### Error Handling
- **HTTPException**: 400 if invalid request or content violates policies
- **HTTPException**: 402 if insufficient credits
- **HTTPException**: 500 if generation could not be started
```

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

### Prepare Media Asset Upload

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

Prepares for uploading a local media file by providing a signed upload URL and necessary information.

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

### Description
Prepares for uploading a local media file by providing a signed upload URL and necessary information.

### Method
POST

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

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

### Request Example
```json
{
  "file_name": "my-video.mp4",
  "kind": "video",
  "extension": "mp4"
}
```

### Response
#### Success Response (200)
- **media_asset** (object) - Information about the created media asset.
  - **id** (string) - The unique identifier for the media asset.
  - **file_name** (string) - The name of the file.
  - **kind** (string) - The type of media asset.
  - **extension** (string) - The file extension.
  - **created_at** (string) - The timestamp when the asset was created.
  - **updated_at** (string) - The timestamp when the asset was last updated.
  - **metadata** (object) - Any associated metadata.
- **upload_info** (object) - Information required for uploading the file.
  - **upload_url** (string) - The signed URL to upload the file to.
  - **upload_method** (string) - The HTTP method to use for uploading (e.g., "PUT").
  - **required_headers** (object) - Any required headers for the upload request.

#### Response Example
```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"
    }
  }
}
```
```

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

### Get World by ID

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

Retrieves a world's details by its unique identifier. Access is restricted to the world owner or users with permissions for public worlds.

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

### 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.

### Method
GET

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

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

### Responses
#### Success Response (200)
- **World object** - Contains world_id, display_name, tags, assets, created_at, updated_at, permission, model, world_prompt, and world_marble_url.

#### Error Response (404)
- World not found or access denied.

#### Error Response (422)
- Validation Error
```

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

### VideoPrompt

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

Supports video input for world generation, with an optional text prompt.

```APIDOC
## VideoPrompt

### Description
Generates a world from a video and an optional text prompt.

### Parameters
#### Request Body
- **video_prompt** (Content) - Required - The input video.
- **text_prompt** (string | null) - Optional - Text prompt to guide generation.
- **type** (string) - Required - Must be 'video'.
```

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

### Operation Response Object

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

This is an example of the Operation object returned after initiating a world generation request. It includes an operation ID that can be used to poll for status.

```json
{
  "operation_id": "20bffbb1-4ba7-453f-a116-93eaw1a6843e",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "expires_at": "2025-01-15T11:30:00Z",
  "done": false,
  "error": null,
  "metadata": null,
  "response": null
}
```

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

### Get Operation Status

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

Poll this endpoint to check the status of a long-running operation. The response includes details about the operation's progress and the final result if completed.

```python
from marble.api.v1.clients import operations

operation_id = "..."
response = operations.get_operation_marble_v1_operations__operation_id__get(operation_id=operation_id)
```

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

### Get Operation by ID

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

Fetches the details of a specific operation using its unique identifier. This is useful for tracking the progress of asynchronous tasks like world generation.

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

### 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.

### Method
GET

### Endpoint
/marble/v1/operations/{operation_id}

### Parameters
#### Path Parameters
- **operation_id** (string) - Required - The operation identifier from /worlds:generate.

### Responses
#### Success Response (200)
- **operation_id** (string) - Operation identifier
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp
- **expires_at** (string) - Expiration timestamp
- **done** (boolean) - true when complete, false while in progress
- **error** (object | null) - Error details if failed, null otherwise
- **metadata** (object | null) - Progress information and world_id
- **response** (object | null) - Generated World if done=true, null otherwise

#### Error Response (401)
Unauthorized

#### Error Response (404)
Operation not found

#### Error Response (500)
Request failed
```

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

### Prepare Media Asset Upload

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

Initiates the process for uploading a media asset by providing a file name and type.

```APIDOC
## POST /media/assets/prepare-upload

### Description
Prepares for a media asset upload by specifying the file name and kind of media.

### Method
POST

### Endpoint
/media/assets/prepare-upload

### Request Body
- **file_name** (string) - Required - File name. Max length 64.
- **extension** (string) - Optional - File extension without dot.
- **kind** (MediaAssetKind) - Required - High-level media type (image, video).

### Request Example
{
  "file_name": "my_image.png",
  "extension": "png",
  "kind": "image"
}

### Response
#### Success Response (200)
- **media_asset_id** (string) - Server-generated media asset identifier.
- **upload_url** (string) - URL to upload the media asset to.
- **file_name** (string) - File name.
- **extension** (string) - File extension without dot.
- **kind** (MediaAssetKind) - High-level media type.
- **created_at** (string) - Creation timestamp.

#### Response Example
{
  "media_asset_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "upload_url": "https://example.com/upload/path",
  "file_name": "my_image.png",
  "extension": "png",
  "kind": "image",
  "created_at": "2023-10-27T10:00:00Z"
}
```

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

### Generate World with Multi-Image Prompt (JavaScript)

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

Generates a world using JavaScript's fetch API with a multi-image prompt. Requires media asset IDs and an API key.

```javascript
const response = await fetch('https://api.worldlabs.ai/marble/v1/worlds:generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'WLT-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    display_name: 'My Multi-Image World',

```

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

### Get World by ID

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

Fetches a world's details using its unique identifier. Access is restricted to the world owner or users with permissions for public worlds.

```APIDOC
## Get World by 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
/worlds/{world_id}

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

### Response
#### Success Response (200)
- **world_id** (string) - The unique identifier of the world.
- **display_name** (string) - The display name of the world.
- **tags** (array) - An array of tags associated with the world.
- **assets** (object) - An object containing generated assets for the world.
- **created_at** (string) - The timestamp when the world was created.
- **updated_at** (string) - The timestamp when the world was last updated.
- **permission** (string) - The permission level for accessing the world (e.g., 'private', 'public').
- **model** (string) - The AI model used for the world.
- **world_prompt** (string) - The initial prompt for the world.
- **world_marble_url** (string) - The URL for the world's marble image.

#### Error Response (404)
- World not found or access denied.
```

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

### Generate Video World from URI (Python)

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

Use this endpoint to generate a video world from a remote video file. Ensure the video is accessible via the provided URI.

```python
import requests

url = "https://api.worldlabs.ai/marble/v1/worlds:generate"

payload = {
    "display_name": "My Video World",
    "world_prompt": {
        "type": "video",
        "video_prompt": {
            "source": "uri",
            "uri": "https://example.com/my-video.mp4"
        },
        "text_prompt": "A scenic mountain landscape"
    }
}
headers = {
    "WLT-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

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

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

### Get Media Asset by ID

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

Fetches the metadata of a specific media asset using its ID. This is useful for retrieving details about uploaded files such as images or videos.

```APIDOC
## GET /marble/v1/media-assets/{media_asset_id}

### Description
Get a media asset by ID. Retrieves metadata for a previously created media asset.

### Method
GET

### Endpoint
/marble/v1/media-assets/{media_asset_id}

### Parameters
#### Path Parameters
- **media_asset_id** (string) - Required - The media asset identifier.

### Response
#### Success Response (200)
- **media_asset_id** (string) - Server-generated media asset identifier
- **file_name** (string) - File name
- **extension** (string) - File extension without dot
- **kind** (MediaAssetKind) - High-level media type
- **metadata** (object) - Optional application-specific metadata
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Last update timestamp

#### Response Example
{
  "media_asset_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "file_name": "example.jpg",
  "extension": "jpg",
  "kind": "image",
  "metadata": {
    "caption": "A beautiful sunset"
  },
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:05:00Z"
}

#### Error Response (404)
- **detail** (array) - Details about the error

#### Error Response Example
{
  "detail": [
    {
      "loc": ["path", "media_asset_id"],
      "msg": "Media asset not found",
      "type": "value_error"
    }
  ]
}
```

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

### Reference Media Asset in World Generation

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

After uploading, reference the media asset ID in a world generation request. This example shows how to structure the JSON payload.

```json
{
  "world_prompt": {
    "type": "image",
    "image_prompt": {
      "source": "media_asset",
      "media_asset_id": "<your-media-asset-id>"
    }
  }
}
```

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

### Generate a World from Text Prompt

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

Use this endpoint to create a new world based on a text description. Ensure you have a valid API key and specify the desired model. The response will be an Operation object.

```bash
curl -X POST 'https://api.worldlabs.ai/marble/v1/worlds:generate' \
  -H 'Content-Type: application/json' \
  -H 'WLT-Api-Key: YOUR_API_KEY' \
  -d '{
    "display_name": "Mystical Forest",
    "model": "marble-1.1",
    "world_prompt": {
      "type": "text",
      "text_prompt": "A mystical forest with glowing mushrooms"
    }
  }'
```

```javascript
const response = await fetch('https://api.worldlabs.ai/marble/v1/worlds:generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'WLT-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    display_name: 'Mystical Forest',
    model: 'marble-1.1',
    world_prompt: {
      type: 'text',
      text_prompt: 'A mystical forest with glowing mushrooms'
    }
  })
});

const data = await response.json();

console.log(data);
```

```python
import requests

url = "https://api.worldlabs.ai/marble/v1/worlds:generate"

payload = {
    "display_name": "Mystical Forest",
    "model": "marble-1.1",
    "world_prompt": {
        "type": "text",
        "text_prompt": "A mystical forest with glowing mushrooms"
    }
}
headers = {
    "WLT-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

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

print(response.text)
```