数据处理

数据处理提供丰富的文件处理能力，无需下载文件即可在云端完成处理。

图片处理

对图片进行裁剪、缩放、水印、格式转换等操作，优化用户体验和节省带宽成本。

开通后：

✅ 图片基础处理：默认开启，可直接使用
⚙️ 图片极智压缩：需要手动开启
⚙️ 图片高级压缩：需要手动开启

功能	说明
基础图片处理	支持裁剪、缩放、旋转、格式转换、质量变换、高斯模糊、锐化等操作
图片极智压缩	支持图片访问时无需参数自动压缩或通过处理参数 imageSlim 主动压缩，支持 JPG、静态 PNG、GIF 三种格式，压缩后不会改变图片格式
图片高级压缩	通过处理参数 imageMogr2/format 将图片转换为 AVIF、HEIF、TPG、ASTC 压缩格式，也支持对 SVG 图片进行压缩

文档处理

将文档转换为 HTML 或图片，实现在线预览功能。

📌 功能支持说明

目前 CloudBase 云存储支持以下文档处理功能：

✅ 文档转 HTML：支持 Word、Excel、PPT、PDF 等格式转换为 HTML 进行在线预览
✅ 文档转图片：支持将文档转换为图片格式（PNG、JPG）

暂不支持：视频和音频等多媒体处理功能。

功能	说明	支持格式
文档转 HTML	将文档转为 HTML 在线预览	Word、Excel、PPT、PDF 等
文档转图片	将文档转为图片格式	Word、Excel、PPT、PDF 等

应用场景：

在线文档查看：无需下载即可在浏览器中预览文档
文档内容展示：将文档内容转为图片或 HTML 展示在应用中
知识库系统：文档内容搜索和展示

操作步骤

图片基础处理

📌 功能说明

图片基础处理支持通过 URL 参数实时处理图片，无需预先配置。默认开启。

可在 云开发平台 - 云存储 页面点击「前往 COS 存储桶」，在左侧菜单「数据处理」→「图片处理」中查看「图片基础处理」模块。

1. 使用 URL 参数处理

在图片访问 URL 后添加处理参数即可：

https://your-bucket.cos.ap-region.myqcloud.com/image.jpg?imageMogr2/thumbnail/!50p

💡 获取图片 URL

如需获取云存储中图片的临时访问链接，请参考获取临时链接。

2. 常用处理参数

操作	参数	取值	示例
缩放·按百分比等比缩放	`imageMogr2/thumbnail/!<Scale>p`	1-1000，如 50p	`imageMogr2/thumbnail/!50p`
缩放·指定宽度等比缩放	`imageMogr2/thumbnail/<W>x`	1-10000，如 200x	`imageMogr2/thumbnail/200x`
缩放·指定高度等比缩放	`imageMogr2/thumbnail/x<H>`	1-10000，如 200	`imageMogr2/thumbnail/x200`
缩放·限定宽高最大值等比缩放	`imageMogr2/thumbnail/<W>x<H>`	1-10000	`imageMogr2/thumbnail/200x200`
缩放·强制缩放（可能变形）	`imageMogr2/thumbnail/<W>x<H>!`	1-10000	`imageMogr2/thumbnail/200x200!`
裁剪·自定义裁剪	`imageMogr2/cut/<W>x<H>x<dx>x<dy>`	宽 × 高 × 水平偏移 × 垂直偏移	`imageMogr2/cut/600x600x100x10`
裁剪·缩放裁剪（指定锚点）	`imageMogr2/crop/<W>x<H>/gravity/<pos>`	pos：center / north / south 等九宫格	`imageMogr2/crop/300x400/gravity/center`
裁剪·圆角裁剪	`imageMogr2/rradius/<radius>`	1 ~ 原图最小边的一半	`imageMogr2/rradius/100`
旋转·顺时针旋转	`imageMogr2/rotate/<deg>`	0-360，如 90	`imageMogr2/rotate/90`
格式·格式转换	`imageMogr2/format/<type>`	jpg / png / webp / gif / heif / avif / tpg / astc / src	`imageMogr2/format/webp`
格式·静图与动图分别转码	`imageMogr2/format/<a>/anima-format/<b>`	动图支持 gif / png / webp / avif	`imageMogr2/format/jpg/anima-format/gif`
质量·相对质量（按原图百分比）	`imageMogr2/rquality/<v>`	0-100	`imageMogr2/rquality/60`
质量·最低质量（兜底提升）	`imageMogr2/lquality/<v>`	0-100	`imageMogr2/lquality/80`
效果·高斯模糊	`imageMogr2/blur/<r>x<s>`	下载时 1-500，上传时 1-50	`imageMogr2/blur/8x5`
效果·锐化	`imageMogr2/sharpen/<v>`	10-300，推荐 70	`imageMogr2/sharpen/70`
效果·亮度调节	`imageMogr2/bright/<v>`	-100 ~ 100	`imageMogr2/bright/70`
效果·对比度调节	`imageMogr2/contrast/<v>`	-100 ~ 100	`imageMogr2/contrast/-50`

3. 创建图片样式（可选）

如果需要复用相同的处理规则，可以创建图片样式：

在 云开发平台 - 云存储 页面点击「前往 COS 存储桶」
在左侧菜单「数据处理」→「图片处理」中点击「样式管理」→「添加样式」
配置处理参数并命名样式（如 thumbnail）
使用样式：image.jpg?imageView2/style/thumbnail

4. 高级处理示例

# 缩放 + 格式转换 + 质量调整（组合使用）
https://example.com/image.jpg?imageMogr2/thumbnail/!50p/format/webp/rquality/80

# 裁剪 + 旋转
https://example.com/image.jpg?imageMogr2/crop/300x300/rotate/90

# 添加文字水印
https://example.com/image.jpg?watermark/2/text/Q2xvdWRCYXNl/font/SGVsdmV0aWNh/fontsize/30/fill/IzAwMDAwMA==/dissolve/80/gravity/southeast/dx/10/dy/10

图片极智压缩

图片极智压缩能够在保证视觉效果的前提下，大幅降低图片体积。支持 JPG、静态 PNG、GIF 三种格式，压缩后不会改变图片格式。

1. 开通极智压缩

在 云开发平台 - 云存储 页面点击「前往 COS 存储桶」
在左侧菜单「数据处理」→「图片处理」中找到「图片极智压缩」模块
点击「开通服务」并确认开通（按调用次数计费）

2. 使用极智压缩

有两种方式可以按需求开启：

方式一：自动压缩（推荐）

无需添加任何额外的参数，在正常访问 JPG、PNG、GIF 格式图片时将自动进行压缩：

# 直接访问图片，自动压缩
https://your-bucket.cos.ap-region.myqcloud.com/image.jpg

方式二：API 压缩

访问图片时，在图片链接后添加极智压缩参数 imageSlim，即可访问到压缩后的图片：

# 使用 imageSlim 参数主动压缩
https://your-bucket.cos.ap-region.myqcloud.com/image.jpg?imageSlim

📖 参考文档

更多详细参数说明，请参考图片极智压缩接口说明。

3. 压缩效果对比

极智压缩可以在不改变图片格式的前提下，显著减小文件体积：

格式	压缩前	压缩后	压缩率	视觉质量
JPG	500 KB	250 KB	50%	无明显差异
PNG	800 KB	400 KB	50%	无明显差异
GIF	1 MB	500 KB	50%	无明显差异

图片高级压缩

图片高级压缩通过 imageMogr2/format 参数将图片转换为 AVIF、HEIF、TPG、ASTC 等高压缩率格式，也支持对 SVG 图片进行压缩。

1. 启用高级压缩功能

在 云开发平台 - 云存储 页面点击「前往 COS 存储桶」
在左侧菜单「数据处理」→「图片处理」中找到「图片高级压缩」选项
点击「开通服务」并确认开通（按调用次数计费）

2. 支持的压缩格式

格式	参数	压缩率	兼容性
HEIF	`imageMogr2/format/heif`	比 JPG 减小 80% 以上	iOS 11+、Android P+ 原生支持
AVIF	`imageMogr2/format/avif`	新一代格式，压缩率最高	Chrome 85+、Firefox 93+
TPG	`imageMogr2/format/tpg`	腾讯自研格式，压缩率极高	需客户端 SDK 支持
ASTC	`imageMogr2/format/astc`	适用于纹理压缩	OpenGL ES 3.0+

3. 使用方式

方式一：下载时处理（不保存）

在图片访问 URL 后添加处理参数：

# 转换为 HEIF 格式
https://your-bucket.cos.ap-region.myqcloud.com/image.jpg?imageMogr2/format/heif

# 转换为 AVIF 格式
https://your-bucket.cos.ap-region.myqcloud.com/image.jpg?imageMogr2/format/avif

# 转换为 TPG 格式
https://your-bucket.cos.ap-region.myqcloud.com/image.jpg?imageMogr2/format/tpg

方式二：上传时处理（保存结果）

在图片上传时同时进行压缩处理并保存：

// 请求头中添加 Pic-Operations
{
  "is_pic_info": 1,
  "rules": [{
    "fileid": "compressed-image.heif",
    "rule": "imageMogr2/format/heif"
  }]
}

方式三：云上数据处理（处理已有图片）

对已存储的图片进行处理并保存：

POST /<ObjectKey>?image_process HTTP/1.1
# 请求体与上传时处理相同

📖 参考文档

4. 压缩效果对比

格式	文件大小	压缩率	适用场景
原图（PNG）	1335.2 KB	-	原始图片
HEIF	52.87 KB	96.0%	iOS/Android 移动端
AVIF	约 50 KB	96.3%	现代浏览器
TPG	约 55 KB	95.9%	腾讯生态应用

文档转 HTML

将文档转换为 HTML 格式，实现在线预览功能。

1. 开通文档预览服务

在 云开发平台 - 云存储 页面点击「前往 COS 存储桶」
在左侧菜单「数据处理」→「文档处理」中点击「开通服务」
确认开通文档预览功能

2. 使用文档转 HTML

通过 URL 参数直接预览文档：

https://your-bucket.cos.ap-region.myqcloud.com/document.pdf?ci-process=doc-preview&dstType=html

核心参数：

参数	必选	说明	取值
`ci-process`	是	指定数据万象处理能力	固定为 `doc-preview`
`dstType`	是	输出目标文件类型	固定为 `html`（小写）
`srcType`	否	输入源文件类型	不填则根据文件后缀自动识别（如 `pptx`、`pdf`、`docx`）
`sign`	否	对象下载签名	私有读文件必须传入，需 URLencode
`copyable`	否	是否允许复制内容	`1`=可复制（默认），`0`=不可复制
`htmlParams`	否	自定义配置参数（JSON）	需进行 URL 安全的 Base64 编码
`htmlwaterword`	否	水印文字内容	需进行 URL 安全的 Base64 编码
`htmlfillstyle`	否	水印颜色和透明度	RGBA 格式（如 `rgba(192,192,192,0.6)`），需 Base64 编码
`htmlfront`	否	水印文字样式	如 `bold 20px Serif`，需 Base64 编码
`htmlrotate`	否	水印旋转角度	0-360，默认 315
`htmlhorizontal`	否	水印水平间距	单位 px，默认 50
`htmlvertical`	否	水印垂直间距	单位 px，默认 100

使用示例：

# 基础预览
https://your-bucket.cos.ap-region.myqcloud.com/test.pptx?ci-process=doc-preview&dstType=html

# 禁止复制 + 添加水印（"test" 的 Base64 编码为 dGVzdAog）
https://your-bucket.cos.ap-region.myqcloud.com/test.pptx?ci-process=doc-preview&dstType=html&copyable=0&htmlwaterword=dGVzdAog

# 切换为英文界面（htmlParams 需 Base64 编码）
https://your-bucket.cos.ap-region.myqcloud.com/test.pptx?ci-process=doc-preview&dstType=html&htmlParams=eyJjb21tb25PcHRpb25zIjp7Imxhbmd1YWdlIjoiZW4ifX0

htmlParams 配置示例：

// 隐藏头部、切换语言为英文
{
  "mode": "normal",
  "commonOptions": {
    "isShowHeader": false,
    "language": "en"
  }
}
// 编码后作为 htmlParams 参数值

📖 参考文档

详细使用说明请参考文档转 HTML 使用指引。

3. 支持的文档格式

演示文件：pptx, ppt, pot, potx, pps, ppsx, dps, dpt, pptm, potm, ppsm
文字文件：doc, dot, wps, wpt, docx, dotx, docm, dotm
表格文件：xls, xlt, et, ett, xlsx, xltx, xlsb, xlsm, xltm, ets
其他格式：pdf, txt, log, xml, htm, html, 代码文件等

4. 注意事项

文件大小限制：输入文件大小需在 200MB 以内
页数限制：输入文件页数限制在 5000 页以内
编码要求：htmlParams、htmlwaterword 等字符串参数必须进行 URL 安全的 Base64 编码
权限要求：私有读文件必须传入 sign 参数进行鉴权

文档转图片

将文档每一页转换为图片格式。

1. 使用 URL 参数转换

通过 URL 参数实时转换文档为图片：

https://your-bucket.cos.ap-region.myqcloud.com/document.pdf?ci-process=doc-preview&page=1&dstType=png

核心参数：

参数	说明	取值
`ci-process`	必选，指定数据万象处理能力	固定为 `doc-preview`
`page`	可选，转换的文档页码	整数，从 1 开始，默认转换第 1 页
`dstType`	可选，输出图片格式	`png` 或 `jpg`，默认为 `jpg`
`srcType`	可选，源文件后缀类型	当文件无后缀时需指定（如 `pptx`、`pdf`、`docx`）
`scale`	可选，预览图片缩放比例	10-200，默认 100（即 100%）
`quality`	可选，生成图片的质量	1-100，默认 100
`imageDpi`	可选，按指定 DPI 渲染图片	96-600，默认 96（注意：高 DPI 会增加处理时间）

使用示例：

# 基础转换：转换第 1 页为 PNG
https://your-bucket.cos.ap-region.myqcloud.com/document.pdf?ci-process=doc-preview&page=1&dstType=png

# 指定质量和缩放：转换为 JPG，质量 85，缩放 50%
https://your-bucket.cos.ap-region.myqcloud.com/document.pdf?ci-process=doc-preview&page=1&dstType=jpg&quality=85&scale=50

# 结合图片处理：转换后添加水印（需 URL 编码）
https://your-bucket.cos.ap-region.myqcloud.com/test.pptx?ci-process=doc-preview&page=1&ImageParams=imageMogr2/thumbnail/!50p|watermark/2/text/dGVzdA/fontsize/30

📖 参考文档

文档转图片使用指引
支持通过 ImageParams 参数结合图片处理功能（如缩放、水印、裁剪等）

2. 支持的文档格式

Microsoft Office：Word（.doc/.docx）、Excel（.xls/.xlsx）、PowerPoint（.ppt/.pptx）
PDF 文档（.pdf）

3. 注意事项

超时限制：同步接口默认 10 秒转换超时，适用于百页以内的文档或预览少数页面
文件限制：输入文件大小限制在 200MB 以内，页数限制在 5000 页以内
私有读存储桶：URL 需要携带 COS 授权签名

常见问题

Q: 图片处理是否会改变原图？

A: 不会。图片处理是实时处理，不会修改原始文件。处理后的图片在访问时动态生成。

Q: 如何保存处理后的图片？

A: 有两种方式：

持久化处理：在处理参数中添加 |saveas 参数，将处理结果保存为新文件
下载后上传：将处理后的图片下载到本地，再上传到存储桶

Q: 处理后的图片会缓存吗？

A: 会。处理后的图片会在 CDN 节点缓存，后续访问相同 URL 时直接返回缓存结果，无需重复处理。

Q: 文档预览是否支持加密文档？

A: 目前不支持加密文档的预览。需要先解密后再上传到存储桶进行预览。

Q: 如何批量处理图片？

A: 可以使用以下方式：

工作流：在控制台创建工作流，自动处理新上传的文件
批量处理任务：在控制台创建批量处理任务，处理已有文件
SDK：通过代码遍历文件列表，调用处理 API

图片处理​

文档处理​

操作步骤​

图片基础处理​

图片极智压缩​

图片高级压缩​

文档转 HTML​

文档转图片​

常见问题​

Q: 图片处理是否会改变原图？​

Q: 如何保存处理后的图片？​

Q: 处理后的图片会缓存吗？​

Q: 文档预览是否支持加密文档？​

Q: 如何批量处理图片？​

相关资源​

图片处理

文档处理

操作步骤

图片基础处理

图片极智压缩

图片高级压缩

文档转 HTML

文档转图片

常见问题

Q: 图片处理是否会改变原图？

Q: 如何保存处理后的图片？

Q: 处理后的图片会缓存吗？

Q: 文档预览是否支持加密文档？

Q: 如何批量处理图片？

相关资源