文档列表只要首页缩略图：用ComPDF按页输出，检查尺寸和清晰度

文档列表只显示首页，没有必要在上传时把整份PDF都转成高清图片。先确定需要哪一页、显示多大，再选择输出参数。

下面用一份三页教学PDF调用ComPDF接口，实际检查首页输出、图像尺寸和返回格式。样本含中文、编号和表格细线，不含客户资料。可下载教学输入与两份PNG结果复核，压缩包内附参数和尺寸说明。

只请求第一页

ComPDF的PDF转图片接口支持页范围、图像格式和缩放。执行前，在服务端配置环境变量COMPDF_API_KEY，准备自己的sample.pdf。示例使用官方海外节点，实际节点按账号及数据处理要求选择。

curl --fail-with-body --request POST \
  'https://api-server.compdf.com/server/v2/process/pdf/img' \
  --header "x-api-key: $COMPDF_API_KEY" \
  --form 'file=@sample.pdf' \
  --form 'pageRanges=1' \
  --form 'imageFormat=PNG' \
  --form 'imageScaling=1' \
  --output response.json

先检查HTTP状态与JSON里的业务状态，再读取结果地址。curl --fail-with-body不能识别所有HTTP 200响应中的业务错误。下载后的文件也要按实际格式处理；本次得到的是ZIP，各包含一张PNG，不能把JSON或ZIP直接改名成PNG。

缩放改变像素，不等于设置固定宽度

同一教学文件分别使用imageScaling=1与2，其他参数相同，两次都成功输出首页。

配置	输出像素	PNG字节数	ZIP字节数
imageScaling=1	595×842	47,647	49,462
imageScaling=2	1190×1684	124,375	138,679

这组数字只描述本次教学样本，不是吞吐或压缩率测试。两份输出都只包含第一页，第二、三页没有进入结果包。

图：同一教学PDF的实际输出。两张图按相同页面比例展示，下面分别标明原始像素与文件字节数。

本次还测试了imageScaling=0.5，接口拒绝该请求，并提示DPI需处于72至1500之间，imageScaling = DPI / 72。因此不要为了缩小图片直接使用0.5；按当前版本允许的取值生成结果，再做列表展示所需的缩放。

浏览器用CSS把大图缩成200像素宽，并不会减少已经下载的字节数。列表缩略图与放大阅读图应分开准备。

检查小字和页面方向

在输出中核对编号PART-0007、参考数值84.70和表格边缘。放大阅读时，选择有足够像素的版本；只在列表中识别文档封面时，再按实际显示要求处理缩略图。

横向、旋转和含透明区域的页面需要单独测试。本次样本为普通竖向页面，不能据此承诺其他页面都不需要调整。图像也不能保留选字、搜索和批注交互；有这些需求时应评估PDF阅读器集成。

资源开销按部署方式判断

2480×3508的RGBA位图，单个像素缓冲约33.2MiB，尚不含其他开销。这是计算估算，不是ComPDF运行内存。

云API的主要转换在远端，应用侧仍需关注下载、解码和缓存。自托管或本地SDK则应测量对应进程，不能用云端请求的结果推断本机转换占用。

缓存标识包含输入摘要、页码、格式和缩放，替换同名文件时生成新标识。确认图像可解码后再交付，失败时不缓存空白图。

需要在系统里持续生成预览图，可通过开发者试用入口验证自己的授权样本。先检查输出与使用场景是否匹配，再确定调用规模和存储配置。