# 媒体与资产

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

> Markdown version of https://kanorio.com/zh-CN/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-CN/help/media