结论先行：智压通 SmartSlim Server 提供RESTful API，包含上传压缩、批量压缩、状态查询、回调通知4大接口，支持API Key和Bearer Token两种认证方式。单文件上传压缩100MB PDF约8秒完成，批量压缩100个文件约12秒。默认限流每分钟60次请求，企业版可提升至300次。本文给出4大接口的参数详解表、Python/JavaScript/curl调用示例和错误处理方案。下面从API总览讲起，逐一详解各接口。
如果你需要通过SDK本地集成而非HTTP API调用，建议先阅读压缩SDK集成指南：Python/Java/C#多语言调用。
一、API接口总览
智压通 SmartSlim Server 的RESTful API基于FastAPI框架开发，所有接口返回JSON格式数据，支持multipart/form-data文件上传。API基础路径为/api/v1/，所有请求必须携带认证信息。
| 接口 | 方法 | 路径 | 功能 | 同步/异步 |
|---|---|---|---|---|
| 上传压缩 | POST | /api/v1/compress | 上传单文件并压缩 | 同步(50MB以下)/异步 |
| 批量压缩 | POST | /api/v1/compress/batch | 批量上传多文件压缩 | 异步 |
| 状态查询 | GET | /api/v1/status/{task_id} | 查询压缩任务状态 | 同步 |
| 回调通知 | POST | 客户端回调URL | 压缩完成后主动通知 | 异步推送 |
认证方式分两种：API Key认证适合服务端调用，Bearer Token认证适合前端调用。下表对比两种认证方式的特点。
| 认证方式 | 请求头 | 有效期 | 适用场景 | 安全性 |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | 永久(可吊销) | 服务端调用 | 中(需HTTPS) |
| Bearer Token | Authorization: Bearer token | 24小时 | 前端调用 | 高(短期有效) |
二、各接口参数详解
1. 上传压缩接口
上传压缩接口接收单个文件，返回压缩结果。50MB以下文件同步返回压缩后的下载链接，50MB以上异步返回任务ID。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| file | multipart/file | 是 | - | 待压缩文件 |
| format | string | 否 | 自动检测 | 文件类型(pdf/image/ofd) |
| level | string | 否 | medium | 压缩级别(low/medium/high/ultra) |
| quality | integer | 否 | 75 | 质量因子(1-100) |
| callback_url | string | 否 | - | 异步回调通知URL |
2. 批量压缩接口
批量压缩接口接收多个文件，异步处理，返回批量任务ID。支持指定并发数，最大并发受授权限制。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| files | multipart/file[] | 是 | - | 待压缩文件列表(最多100个) |
| level | string | 否 | medium | 压缩级别 |
| quality | integer | 否 | 75 | 质量因子 |
| workers | integer | 否 | 4 | 并发数(1-16) |
| callback_url | string | 否 | - | 完成回调URL |
3. 状态查询接口
状态查询接口通过任务ID查询异步压缩任务的当前状态和结果。
| 返回字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | 任务唯一标识 |
| status | string | 状态(pending/processing/completed/failed) |
| progress | integer | 进度百分比(0-100) |
| download_url | string | 压缩结果下载链接(完成后) |
| original_size | integer | 原始文件大小(字节) |
| compressed_size | integer | 压缩后大小(字节) |
| error | string | 错误信息(失败时) |
三、三种语言调用示例
下面给出curl、Python、JavaScript三种语言的调用示例，均以上传压缩单个PDF文件为例。
| 语言 | 核心代码 | 说明 |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | 命令行调用 |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | requests库 |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | Fetch API |
四、限流与错误处理
API有完善的限流和错误处理机制。理解HTTP状态码和错误码，才能写出健壮的调用代码。
| HTTP状态码 | 错误码 | 含义 | 处理建议 |
|---|---|---|---|
| 200 | - | 成功 | 解析响应数据 |
| 400 | INVALID_PARAM | 参数错误 | 检查请求参数 |
| 401 | UNAUTHORIZED | 认证失败 | 检查API Key/Token |
| 413 | FILE_TOO_LARGE | 文件超限 | 使用分块上传 |
| 429 | RATE_LIMITED | 请求过频 | 指数退避重试 |
| 500 | INTERNAL_ERROR | 服务器错误 | 重试或联系支持 |
| 503 | SERVICE_UNAVAILABLE | 服务不可用 | 等待后重试 |
限流策略细节：默认每分钟60次请求、每秒10次并发，企业版每分钟300次、每秒30并发。超过限制返回429，响应头包含X-RateLimit-Remaining（剩余次数）和X-RateLimit-Reset（重置时间戳）。建议客户端实现指数退避重试：收到429后等待1秒重试，再失败等2秒，再失败等4秒，最多重试3次。
| 文件类型 | 原始大小 | 压缩后大小 | 压缩耗时 | 压缩率 |
|---|---|---|---|---|
| PDF(扫描件) | 80MB | 8.2MB | 6.5秒 | 89.8% |
| PDF(电子版) | 15MB | 3.1MB | 1.2秒 | 79.3% |
| JPEG图片 | 12MB | 2.8MB | 0.8秒 | 76.7% |
| PNG图片 | 25MB | 6.5MB | 1.5秒 | 74.0% |
| OFD文档 | 30MB | 5.2MB | 2.0秒 | 82.7% |
如果你需要了解压缩任务队列的底层设计原理，可以参考压缩任务队列设计。如果你需要通过Docker部署API服务，可以参考Docker部署压缩服务。
五、常见问题FAQ
Q1：压缩API怎么认证调用？
智压通 SmartSlim Server 的压缩API支持两种认证方式：API Key认证（在请求头X-API-Key中传入密钥，适合服务端调用）和Bearer Token认证（在Authorization头中传入JWT Token，适合前端调用）。API Key永久有效但可随时吊销，Token有效期为24小时需要定期刷新。生产环境推荐API Key方式，简单可靠。
Q2：压缩API支持哪些文件格式？
智压通服务器版API支持PDF、图片（jpg/jpeg/tif）、OFD格式，单文件上限1GB。智压通网络版API支持全部10大类40+格式（含视频、音频、Office文档等），单文件上限10GB。调用时通过format参数指定文件类型，不传则自动检测。注意服务器版仅支持PDF/图片/OFD三种格式，全格式需网络版。
Q3：压缩API有调用频率限制吗？
有限流策略保护服务稳定性。默认限流：每分钟60次请求，每秒10次并发。超过限制返回429状态码，响应头包含X-RateLimit-Remaining和X-RateLimit-Reset字段。企业版可提升至每分钟300次、每秒30并发。建议客户端实现指数退避重试机制，收到429后等待1-2-4秒递增重试。
Q4：压缩API大文件怎么处理？
大文件（超过50MB）推荐使用分块上传接口，将文件分成多个5MB分块上传，全部上传完成后通知合并压缩。压缩完成后通过回调通知或轮询状态查询接口获取结果。大文件压缩是异步的，不会阻塞API调用。100MB PDF压缩约需8秒，1GB视频压缩约需90秒，完成后自动生成下载链接。
总结
智压通 SmartSlim Server 的RESTful API提供4大接口——上传压缩、批量压缩、状态查询、回调通知，覆盖从单文件到批量处理的全场景。认证方式双选：API Key适合服务端，Bearer Token适合前端。限流策略明确：默认每分钟60次，企业版300次，429状态码配合指数退避重试。80MB扫描PDF压缩到8.2MB仅需6.5秒，压缩率89.8%。
记住三点：一是50MB以下同步返回结果，以上异步用任务ID查询；二是限流429要实现指数退避重试，别硬刷；三是大文件用分块上传接口，5MB一块分批上传。选对接口和参数，压缩API的调用其实很简单。如果你更倾向本地SDK集成而非HTTP调用，可以参考压缩SDK集成指南。