# Assets

## Download

`$client->assets->download(string url): 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: string`

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

### Returns

- `AssetDownloadResponse`

  - `?string error`

    Error message if the download failed.

  - `?string srcURL`

    Local file URL to the downloaded asset.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client();

$response = $client->assets->download(
  url: 'mxc://example.org/Q4x9CqGz1pB3Oa6XgJ'
);

var_dump($response);
```

## Upload

`$client->assets->upload(string file, ?string fileName, ?string mimeType): 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: string`

  The file to upload (max 500 MB).

- `fileName?:optional string`

  Original filename. Defaults to the uploaded file name if omitted

- `mimeType?:optional string`

  MIME type. Auto-detected from magic bytes if omitted

### Returns

- `AssetUploadResponse`

  - `?float duration`

    Duration in seconds (audio/videos)

  - `?string error`

    Error message if upload failed

  - `?string fileName`

    Resolved filename

  - `?float fileSize`

    File size in bytes

  - `?float height`

    Height in pixels (images/videos)

  - `?string mimeType`

    Detected or provided MIME type

  - `?string srcURL`

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

  - `?string uploadID`

    Unique upload ID for this asset

  - `?float width`

    Width in pixels (images/videos)

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client();

$response = $client->assets->upload(
  file: 'file', fileName: 'fileName', mimeType: 'mimeType'
);

var_dump($response);
```

## Upload Base64

`$client->assets->uploadBase64(string content, ?string fileName, ?string mimeType): 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: string`

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

- `fileName?:optional string`

  Original filename. Generated if omitted

- `mimeType?:optional string`

  MIME type. Auto-detected from magic bytes if omitted

### Returns

- `AssetUploadBase64Response`

  - `?float duration`

    Duration in seconds (audio/videos)

  - `?string error`

    Error message if upload failed

  - `?string fileName`

    Resolved filename

  - `?float fileSize`

    File size in bytes

  - `?float height`

    Height in pixels (images/videos)

  - `?string mimeType`

    Detected or provided MIME type

  - `?string srcURL`

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

  - `?string uploadID`

    Unique upload ID for this asset

  - `?float width`

    Width in pixels (images/videos)

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client();

$response = $client->assets->uploadBase64(
  content: 'x', fileName: 'fileName', mimeType: 'mimeType'
);

var_dump($response);
```

## Serve

`$client->assets->serve(string url): void`

**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: string`

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

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client();

$result = $client->assets->serve(url: 'x');

var_dump($result);
```