# Media API

## Available Fields

| Field | Type | Description |
|---|---|---|
| `id` | int | Media file ID |
| `file_name` | string | File name |
| `file_path` | string | Full path or CDN URL to the file |
| `file_type` | string | MIME type (e.g. `image/jpeg`, `image/png`, `video/mp4`, `audio/mpeg`) |
| `file_size` | string | Human-readable file size (e.g. `245 KB`) |
| `resolution` | string | Image resolution (e.g. `1920x1080`) |
| `title` | string | Display title shown in media library |
| `credit` | string | Photo/video credit or source attribution |
| `description` | string | Internal notes or alt text description |
| `cache_versions` | json | Cached size variants (304px, 500px, 800px WebP) |
| `created_at` | datetime | Upload date |

---

## Using Media in Articles and Pages

After uploading a file, use its `id` to:
- Set as article **thumbnail**: `"thumbnail": 15`
- Set as article **video**: `"video_link": 5`
- Set as article **audio/TTS**: `"audio_tts_id": 47`
- Embed **inline** in `body` or `content` via dynamic block:

```html
<dynamic-block data-id="MEDIA_ID" data-type="media" data-size="large" contenteditable="false"></dynamic-block>
```

---

## Get All Media

```json
{
  "resource": "media",
  "action": "get",
  "filters": {
    "file_type": "image/jpeg",
    "search": "banner",
    "date_from": "2025-01-01",
    "date_to": "2025-12-31"
  },
  "fields": ["id", "file_name", "file_path", "file_type", "file_size", "resolution", "title", "created_at"],
  "limit": 20,
  "offset": 0,
  "order_by": "id DESC"
}
```

| Filter | Description |
|---|---|
| `search` | Searches in file name, title, description |
| `file_type` | MIME type (e.g. `image/jpeg`, `image/png`, `video/mp4`) |
| `date_from` | Files uploaded from this date (`YYYY-MM-DD`) |
| `date_to` | Files uploaded up to this date (`YYYY-MM-DD`) |

---

## Get Single Media File

```json
{
  "resource": "media",
  "action": "get",
  "id": 123
}
```

---

## Upload from URL

Downloads a file from a public URL and imports it into the media library. Returns the new media `id` to use in articles/pages.

```json
{
  "resource": "media",
  "action": "upload_from_url",
  "file_url": "https://example.com/image.jpg"
}
```

Supports: images (JPG, PNG, WebP, GIF), video, and audio files.

**Response:**
```json
{
  "status": "success",
  "files": [[{ "id": "48", "file_path": "...", "file_type": "image/jpeg", ... }]]
}
```

---

## Update Metadata

```json
{
  "resource": "media",
  "action": "update_metadata",
  "file_id": 123,
  "title": "Photo title",
  "credit": "Photographer Name / Agency",
  "description": "Photo description or alt text"
}
```

---

## Delete Media

Deletes the file and all its cached size variants.

```json
{
  "resource": "media",
  "action": "delete",
  "file_id": 123
}
```

---

## Create Cache Versions

Regenerates all image cache sizes (304px, 500px, 800px WebP) for every file in the library.

```json
{
  "resource": "media",
  "action": "create_all_cache"
}
```

---

## Delete Cache Versions

Removes all cached size variants for all media files (original files are kept).

```json
{
  "resource": "media",
  "action": "delete_all_cache"
}
```