# 미디어 및 에셋

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

> Markdown version of https://kanorio.com/ko/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를 통해 파일을 참조하며, 응답 시 해당 ID는 URL, 크기, 대체 텍스트 및 플레이스홀더로 해석됩니다.

## 핵심 객체

- **에셋:** 공개 여부, 태그, 대체 텍스트, 초점 및 처리 상태를 포함하는 파일입니다. 공개 파일은 CDN을 통해 제공됩니다. 강의 영상과 같이 보호된 파일은 유효 기간이 짧은 서명된 URL을 통해서만 접근할 수 있습니다.
- **이미지 변형:** 요청 시 크기가 조정된 버전과 모든 이미지에 대한 작은 흐림 효과의 플레이스홀더가 생성됩니다.
- **동영상 스트리밍:** 동영상은 적응형 스트림으로 변환되며, 보호된 동영상의 경우 서명된 세그먼트가 적용됩니다.

## 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/ko/help/media