# Assets

## Download

`assets.download(AssetDownloadParams**kwargs)  -> AssetDownloadResponse`

**post** `/v1/assets/download`

Download a Matrix asset using its mxc:// or localmxc:// URL to the device running Beeper Desktop and return the local file URL.

### Parameters

- `url: str`

  Matrix content URL (mxc:// or localmxc://) for the asset to download.

### Returns

- `class AssetDownloadResponse: …`

  - `error: Optional[str]`

    Error message if the download failed.

  - `src_url: Optional[str]`

    Local file URL to the downloaded asset.

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
response = client.assets.download(
    url="mxc://example.org/Q4x9CqGz1pB3Oa6XgJ",
)
print(response.error)
```

## Upload

`assets.upload(AssetUploadParams**kwargs)  -> AssetUploadResponse`

**post** `/v1/assets/upload`

Upload a file to a temporary location using multipart/form-data. Returns an uploadID that can be referenced when sending messages with attachments.

### Parameters

- `file: FileTypes`

  The file to upload (max 500 MB).

- `file_name: Optional[str]`

  Original filename. Defaults to the uploaded file name if omitted

- `mime_type: Optional[str]`

  MIME type. Auto-detected from magic bytes if omitted

### Returns

- `class AssetUploadResponse: …`

  - `duration: Optional[float]`

    Duration in seconds (audio/videos)

  - `error: Optional[str]`

    Error message if upload failed

  - `file_name: Optional[str]`

    Resolved filename

  - `file_size: Optional[float]`

    File size in bytes

  - `height: Optional[float]`

    Height in pixels (images/videos)

  - `mime_type: Optional[str]`

    Detected or provided MIME type

  - `src_url: Optional[str]`

    Local file URL (file://) for the uploaded asset

  - `upload_id: Optional[str]`

    Unique upload ID for this asset

  - `width: Optional[float]`

    Width in pixels (images/videos)

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
response = client.assets.upload(
    file=b"raw file contents",
)
print(response.width)
```

## Upload Base64

`assets.upload_base64(AssetUploadBase64Params**kwargs)  -> AssetUploadBase64Response`

**post** `/v1/assets/upload/base64`

Upload a file using a JSON body with base64-encoded content. Returns an uploadID that can be referenced when sending messages with attachments. Alternative to the multipart upload endpoint.

### Parameters

- `content: str`

  Base64-encoded file content (max ~500MB decoded)

- `file_name: Optional[str]`

  Original filename. Generated if omitted

- `mime_type: Optional[str]`

  MIME type. Auto-detected from magic bytes if omitted

### Returns

- `class AssetUploadBase64Response: …`

  - `duration: Optional[float]`

    Duration in seconds (audio/videos)

  - `error: Optional[str]`

    Error message if upload failed

  - `file_name: Optional[str]`

    Resolved filename

  - `file_size: Optional[float]`

    File size in bytes

  - `height: Optional[float]`

    Height in pixels (images/videos)

  - `mime_type: Optional[str]`

    Detected or provided MIME type

  - `src_url: Optional[str]`

    Local file URL (file://) for the uploaded asset

  - `upload_id: Optional[str]`

    Unique upload ID for this asset

  - `width: Optional[float]`

    Width in pixels (images/videos)

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
response = client.assets.upload_base64(
    content="x",
)
print(response.width)
```

## Serve

`assets.serve(AssetServeParams**kwargs)`

**get** `/v1/assets/serve`

Stream a file given an mxc://, localmxc://, or file:// URL. Downloads first if not cached. Supports Range requests for seeking in large files.

### Parameters

- `url: str`

  Asset URL to serve. Accepts mxc://, localmxc://, or file:// URLs.

### Example

```python
from beeper_desktop_api import BeeperDesktop

client = BeeperDesktop()
client.assets.serve(
    url="x",
)
```