媒体处理：能力与使用说明
本文介绍通过访问域名使用图片、视频、动图等媒体处理能力的方式，包括每种能力的用途、URL 参数说明与示例、以及计费说明。所有参数均通过 URL 查询参数 传递，无需单独接口。
使用入口与前提
使用前提
- 已在管理后台为存储桶 绑定访问域名（系统管理 → 存储管理 → 存储桶 → 绑定域名，或对象存储 → 存储桶设置 → 绑定域名）。
- 通过该域名访问桶内文件时，在 同一 URL 后追加查询参数 即可触发媒体处理；不追加参数则返回原文件。
基本 URL 形式
https://你的访问域名/桶内路径/文件名?参数1=值1&参数2=值2例如原图地址为 https://cdn.example.com/images/photo.jpg，需要缩放到宽度 200 时：
https://cdn.example.com/images/photo.jpg?w=200处理后的结果会直接作为图片/视频/JSON 返回，可直接用于 <img src="...">、<video> 或接口调用。
1. 截帧
从 视频 或 动图（GIF、动图 WebP 等）中截取单帧，输出为静态图片。常用于生成封面、预览图。
视频截帧
对视频文件在指定 时间点（毫秒） 截取一帧。
| 参数 | 说明 | 示例 |
|---|---|---|
frame | 时间点，单位 毫秒（如 5000 表示第 5 秒） | frame=5000 |
fmt | 截帧输出格式：jpg、png、webp 等 | fmt=jpg |
q | 输出图片质量，1–100（对 JPEG 等有效） | q=85 |
可与图片参数组合：先截帧再按 w、h、radius 等处理。示例：?frame=3000（第 3 秒）、?frame=10000&w=400&fmt=webp&q=85。
说明：依赖服务端 FFmpeg；视频大小、超时等可在「访问配置 → 媒体处理」中配置。
动图截帧
对动图按 帧序号（从 1 开始）截取一帧。
| 参数 | 说明 | 示例 |
|---|---|---|
frame | 帧序号，1 表示第 1 帧 | frame=1 |
fmt、q、w、h 等 | 同图片处理，对截出的帧再处理 | 可组合使用 |
示例：?frame=1（第 1 帧）、?frame=5&w=200。
2. 尺寸
控制输出图片的 缩放 与 裁剪区域，适用于缩略图、固定宽高、按区域裁切等。
缩放
| 参数 | 说明 | 示例 |
|---|---|---|
w | 目标宽度（像素） | w=200 |
h | 目标高度（像素） | h=150 |
dpr | 设备像素比，0.01–10，常与 w/h 配合用于高清屏 | dpr=2 |
mode | 缩放模式：clip（等比缩放到框内，默认）、crop（等比裁剪）、fill（等比填充） | mode=crop |
pos | 裁剪/填充时的参考位置：center、top、bottom、left、right、top-left、top-right、bottom-left、bottom-right、auto | pos=top |
使用示例
- 按宽度缩放到 200px，高度等比：
?w=200 - 指定宽高并裁剪为 200×150：
?w=200&h=150&mode=crop&pos=center - 高清屏缩略图：
?w=400&dpr=2
裁剪（矩形区域）
| 参数 | 说明 | 示例 |
|---|---|---|
rect | 裁剪区域，格式为 x,y,宽,高（像素，左上角为原点） | rect=10,20,300,200 |
使用示例
- 从 (10,20) 开始裁出 300×200 区域：
?rect=10,20,300,200 - 与缩放、质量组合：
?rect=0,0,400,400&w=200&q=85
3. 格式与质量
控制输出图片的 文件格式 与 压缩质量，用于省流量、兼容性等。
| 参数 | 说明 | 示例 |
|---|---|---|
q | 输出质量，1–100，默认 88（仅对 JPEG 等有损格式生效） | q=80 |
fmt | 输出格式：jpg、jpeg、png、gif、webp、avif、bmp、tpng（优化 PNG）、keep（保持原格式） | fmt=webp |
使用示例
- 输出 WebP、质量 85：
?fmt=webp&q=85 - 输出为优化后的 PNG（体积更小）：
?fmt=tpng&q=80
4. 效果
对图片做 锐化、模糊、亮度、对比度、饱和度、灰度、反色、色彩空间 等处理。
| 参数 | 说明 | 示例 |
|---|---|---|
sharp | 锐化程度，0–500 | sharp=100 |
blur | 模糊程度，0–500 | blur=5 |
brightness | 亮度，-100–100 | brightness=10 |
contrast | 对比度，-100–100 | contrast=20 |
saturation | 饱和度，-100–100 | saturation=-30 |
grayscale | 灰度，传 1 或 true | grayscale=1 |
invert | 反色，传 1 或 true | invert=1 |
cs | 色彩空间：keep、srgb、tinysrgb、p3 | cs=srgb |
使用示例
- 略提亮并增加对比度：
?brightness=5&contrast=15 - 灰度图：
?grayscale=1 - 轻度模糊做背景图：
?blur=8&w=800
5. 旋转与圆角
对图片做 旋转、水平/垂直翻转 以及 圆角 处理。
旋转与翻转
| 参数 | 说明 | 示例 |
|---|---|---|
rotate | 旋转角度（度） | rotate=90 |
fliph | 水平翻转，1 或 true | fliph=1 |
flipv | 垂直翻转，1 或 true | flipv=1 |
auto_orient | 根据 EXIF 自动旋转，默认开启；传 0 关闭 | auto_orient=0 |
使用示例：顺时针旋转 90 度 ?rotate=90；水平翻转 ?fliph=1。
圆角
| 参数 | 说明 | 示例 |
|---|---|---|
radius | 圆角半径（像素） | radius=8 |
使用示例
- 8px 圆角：
?radius=8 - 头像圆角：
?w=100&h=100&mode=crop&pos=center&radius=50
6. 图片水印
在图片上叠加 一张图片 作为水印（如 Logo），可调位置、大小比例、透明度。
| 参数 | 说明 | 示例 |
|---|---|---|
mark | 水印图片 URL（需为 http/https） | mark=https://example.com/logo.png |
mark-pos | 水印位置偏移 | 依系统约定 |
mark-pct | 水印相对原图的最大占比，0–2 | mark-pct=0.2 |
mark-alpha | 水印透明度，0–1 | mark-alpha=0.6 |
使用示例
- 在图上叠加 20% 大小、60% 透明度的 Logo：
?mark=https://example.com/logo.png&mark-pct=0.2&mark-alpha=0.6
7. 文字水印
在图片上叠加 文字 作为水印，可调字体、字号、位置、颜色、透明度、阴影等。
| 参数 | 说明 | 示例 |
|---|---|---|
txt | 水印文字内容 | txt=内部使用 |
txt-font | 字体名称，多个用逗号分隔 | txt-font=Microsoft YaHei |
txt-size | 字号；小于 1 时按原图最小边百分比计算 | txt-size=24 |
txt-weight | 字重，100–900 | txt-weight=700 |
txt-pos | 位置：坐标如 0.95,0.95，或位置名如 bottom-right | txt-pos=bottom-right |
txt-pct | 文字区域相对原图的最大占比，0–2 | txt-pct=0.3 |
txt-color | 文字颜色（十六进制，不含 #） | txt-color=FFFFFF |
txt-alpha | 文字透明度，0–1 | txt-alpha=0.8 |
txt-shad | 阴影虚化度，0–50 | txt-shad=2 |
txt-shad-pos、txt-shad-color | 阴影偏移与颜色 | 依系统约定 |
txt-line-height、txt-color-deg | 行高倍数、渐变角度（多色时） | 依系统约定 |
使用示例
- 右下角 24px 白字、80% 透明：
?txt=内部使用&txt-size=24&txt-pos=bottom-right&txt-color=FFFFFF&txt-alpha=0.8
信息类请求（不返回图片）
用于获取图片 元信息 或 主色/色板 等，返回 JSON 或文本，不返回图片本身。
| 参数 | 说明 | 返回 |
|---|---|---|
fmt=info | 图片元信息 | 宽高、格式、是否有透明通道等 JSON |
fmt=color | 主色与调色板 | 主色、色板、亮度等 JSON |
fmt=blurhash | BlurHash 编码 | 文本形式的 BlurHash 字符串 |
fmt=thumbhash | ThumbHash 编码 | 文本形式的 ThumbHash 字符串 |
示例：?fmt=info、?fmt=color。
处理顺序与组合
- 图片处理顺序大致为：裁剪(rect) → 缩放(w/h/mode/pos/dpr) → 效果 → 图片水印 → 文字水印 → 圆角 → 旋转翻转 → 输出格式与质量。
- 视频/动图：先按
frame截帧得到一帧，再对该帧应用上述图片参数。 - 多种能力可自由组合，例如：
?rect=0,0,400,400&w=200&h=200&mode=crop&txt=内部&fmt=webp&q=85。
计费说明
- 图片处理：带图片处理参数的访问按「图片处理」计费（按次）。
- 视频截帧：按「视频处理」计费（按次）。
- 动图截帧：通常计入图片处理或单独规则，以实际计费配置为准。
- 音频处理：若支持，对应「音频处理」计费项。
用量与账单：用户端 → 计费管理 → 账单中心 / 收支明细；管理员：系统管理 → 运维监控 → 计费明细。
常见用法速查
| 场景 | 示例 |
|---|---|
| 列表缩略图 | ?w=200&h=200&mode=crop&pos=center |
| 详情中图 | ?w=800&q=85 |
| 高清屏 2x 图 | ?w=400&dpr=2&q=90 |
| 头像圆角 | ?w=80&h=80&mode=crop&pos=center&radius=40 |
| 输出 WebP 省流量 | ?w=600&fmt=webp&q=82 |
| 视频封面 | ?frame=1000（第 1 秒） |
| 获取图片信息 | ?fmt=info |
| 主色/色板 | ?fmt=color |