# 媒體與資產

> The media library with public and protected files, image variants and placeholders, video streaming and processing status.

> Markdown version of https://kanorio.com/zh-Hant/developers/products/media. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/products/media.md

Status: **Available**

網站使用的每一張圖片、影片與檔案皆存放於媒體庫中。內容透過資產 ID 參照檔案，API 回應會將 ID 解析為 URL、尺寸、替代文字與預留位置。

## 核心物件

- **資產 (Assets)：** 包含檔案的可見性、標籤、替代文字、焦點與處理狀態。公開檔案透過 CDN 傳輸。受保護的檔案（如課程影片）僅能透過短效簽章 URL 存取。
- **圖片變體 (Image variants)：** 按需調整大小的版本，以及每張圖片的微型模糊預留位置。
- **影片串流 (Video streaming)：** 影片會轉換為自適應串流，受保護的影片則會使用簽章片段。

## API 如何運作

- 透過 Management API 使用 URL 或檔案上傳、請求大型檔案的直接上傳 URL、建立客戶端上傳連結，以及匯入庫存照片。
- 每個參照媒體的 Content Delivery API 回應皆包含 `assets` 對應表。
- 使用 `<kanorio-media>` 與 `<kanorio-lightbox>` 播放媒體與顯示圖片。
- Webhooks 會回報資產處理完成或失敗的狀態。

## What the APIs expose

| Capability | Status | API | Elements | Hosted site | Webhooks |
| --- | --- | --- | --- | --- | --- |
| Public & protected media, responsive images, LQIP placeholders, lightbox & HLS video streaming | Available | Management API `media.*` (images and files with `visibility` public/protected, `tags` and `processing`; protected files have no public URL and need only `media:manage`; `media.get` `renditions[]` for public files incl. `hls` and `thumbnails` once a video is transcoded, `streaming` none/processing/partial/ready; `media.update` focus, alt text, tags, visibility switch and `streaming: true` to transcode now); Delivery `assets` map (`url`, `width`, `height`, `alt`, `focus`, `watermarked`, `placeholder` 16px WebP data URL, `processing`, video `renditions` + `streaming`; public assets only); Customer API `POST /units/:id/open` returns `renditions` with a signed `hls` path for protected videos (expiresIn follows the video length); `GET /api/v1/site` `mediaProtection` | `<kanorio-media src mime-type>`, `<kanorio-lightbox images='[…]'>` (reads the site's media protection when `protection` is omitted) | `/media` library; gallery & media sections | `media.asset.ready`, `media.asset.failed` (background processing of a file: thumbnails, visibility moves, transcoding) |

## API reference

- Management API: [Media](https://kanorio.com/en/developers/management-api/media) (15 operations)

## Webhook events

- `media.asset.ready`: Fired when background processing of a media file (thumbnail, visibility move, transcoding) finishes and the file is ready to use.
- `media.asset.failed`: Fired when background processing of a media file fails after retries; the site team also gets an in-app notification.
- `site.storageQuota.alert`: Fired when site storage reaches 80%, is exhausted, auto-upgrades, or add-on payment fails.

Payloads: https://kanorio.com/en/developers/webhooks/events

## Elements

- `<kanorio-media>`: Public media player for a URL.
- `<kanorio-lightbox>`: Image lightbox with zoom, keyboard navigation, and download and share controls that follow the site's media protection.

## Recent changes

- 2026-11-01: Media: adaptive streaming (HLS) versions of videos
- 2026-10-31: Media: visibility is a file property
- 2026-10-24: billableBytes, edgeColor, ogImageFraming, imageFramings, and 20 GB storage add-on levels
- 2026-10-23: Per-device image aspect ratio and image framing in sections
- 2026-10-23: Protected files for deliverables, file uploads and large-file uploads

Full changelog: https://kanorio.com/en/developers/changelog

## For site owners

Dashboard help: https://kanorio.com/zh-Hant/help/media