数据处理

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

图片处理

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

开通后：

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

功能	说明
基础图片处理	支持裁剪、缩放、旋转、格式转换、质量变换、高斯模糊、锐化等操作
图片极智压缩	支持图片访问时无需参数自动压缩或通过处理参数 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/500x	指定宽度为 500px，高度等比缩放
强制缩放	imageMogr2/thumbnail/!300x200	强制缩放为 300x200 像素（忽略宽高比）
按比例缩放	imageMogr2/thumbnail/!50p	缩放为原图的 50%
普通裁剪	imageMogr2/crop/300x300x10x10	从坐标 (10,10) 开始裁剪 300x300 像素区域
智能裁剪	imageMogr2/crop/300x300/gravity/face	根据人脸位置智能裁剪 300x300 像素
旋转	imageMogr2/rotate/90	顺时针旋转 90 度
格式转换	imageMogr2/format/webp	转换为 WebP 格式
质量调整	imageMogr2/quality/85	调整图片质量为 85（取值 1-100）
高斯模糊	imageMogr2/blur/3x5	半径为 3、标准差为 5 的高斯模糊
锐化	imageMogr2/sharpen/3	锐化处理，半径为 3

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

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

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

4. 高级处理示例

# 缩放 + 格式转换 + 质量调整（组合使用）
https://example.com/image.jpg?imageMogr2/thumbnail/!50p/format/webp/quality/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. 开通极智压缩

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

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. 启用高级压缩功能

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

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
# 请求体与上传时处理相同

📖 参考文档

• HEIF 压缩说明
• TPG 压缩说明
• AVIF 压缩说明

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. 开通文档预览服务

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

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: 有两种方式：

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

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

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

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

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

Q: 如何批量处理图片？

A: 可以使用以下方式：

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

---

相关资源

• 图片处理 API 文档
• 文档预览 API 文档
• 文档转 HTML 详细说明
• 文档转图片详细说明
• 图片样式配置指南
• 返回总览页