API文档 - 压缩接口完整说明

智压通压缩 API 完整 OpenAPI 3.0 规范文档，包含所有接口说明、参数定义、错误码参考与限流策略

认证方式

智压通压缩 API 采用 Bearer Token 方式进行身份认证

Bearer Token

API Key 通过 HTTP 请求头 Authorization 传递，格式为 Bearer YOUR_API_KEY。所有接口请求均需携带该头部，缺失或无效将返回 401 错误。

传输安全

所有 API 请求均通过 HTTPS 加密传输，请勿使用 HTTP 明文协议调用，确保 API Key 与文件数据在传输过程中的安全。

API Key 管理

API Key 可在开发者控制台的应用管理中查看、重置与禁用。建议为不同环境（开发/测试/生产）创建独立应用，便于隔离与审计。

# 认证请求头示例
Authorization: Bearer YOUR_API_KEY

接口列表

智压通压缩 API 提供文件压缩、任务管理、批量处理与用量统计等完整接口

POST /v1/compress

文件压缩：上传单个文件并执行压缩。

file（必填）：待压缩文件
quality：压缩质量，可选 low / medium / high
format：输出格式
password（可选）：加密压缩密码

GET /v1/tasks/{task_id}

查询任务状态：根据任务 ID 获取压缩任务的当前状态与结果信息。

返回 status：pending / processing / completed / failed

GET /v1/tasks/{task_id}/download

下载压缩文件：任务完成后，通过该接口下载压缩结果文件，返回文件流。

POST /v1/batch/compress

批量压缩：一次上传多个文件进行批量压缩处理。

files[]（必填）：待压缩文件数组
quality：压缩质量
format：输出格式
callback_url（可选）：任务完成回调地址

GET /v1/usage

查询用量统计：获取当前账户的用量数据，包括本月调用次数、压缩文件总量、存储用量等。

DELETE /v1/tasks/{task_id}

删除任务：根据任务 ID 删除指定的压缩任务及其结果文件，释放存储空间。

文件压缩接口请求示例

POST /v1/compress HTTP/1.1
Host: api.uglypear.com
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

(文件二进制内容)
------FormBoundary
Content-Disposition: form-data; name="quality"

high
------FormBoundary
Content-Disposition: form-data; name="format"

pdf
------FormBoundary--

任务状态查询响应示例

{
  "task_id": "task_8f3c2a1b9e7d4c5f",
  "status": "completed",
  "download_url": "https://api.uglypear.com/v1/tasks/task_8f3c2a1b9e7d4c5f/download",
  "original_size": 5242880,
  "compressed_size": 1572864,
  "compression_ratio": "70.0%",
  "created_at": "2026-08-05T10:00:00Z",
  "completed_at": "2026-08-05T10:00:08Z"
}

错误码参考

接口调用过程中可能返回的 HTTP 状态码及含义说明，便于问题排查与异常处理

HTTP 状态码	名称	说明
200	成功	请求处理成功，返回预期结果数据。
400	请求参数错误	请求参数缺失、格式不正确或超出限制，请检查请求体与参数。
401	API Key 无效或过期	未携带 Authorization 头、API Key 无效或已过期，请重新获取有效密钥。
403	权限不足	当前 API Key 无权访问该资源或操作，请确认套餐权限与资源归属。
429	请求频率超限	请求频率超出当前套餐的限流阈值，请降低调用频率或升级套餐。
500	服务器内部错误	服务端处理过程中发生异常，请稍后重试或联系技术支持。
503	服务暂时不可用	服务正在维护或暂时过载，请稍后重试。

错误响应示例

{
  "error": {
    "code": 429,
    "message": "请求频率超限，当前套餐限制为 60 次/分钟",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

限流策略

不同套餐对应不同的请求频率上限，超限将返回 429 错误，请根据业务量级选择合适套餐

10

免费版
次/分钟

60

基础版
次/分钟

300

专业版
次/分钟

不限

企业版
按需配置

限流以 API Key 为维度进行统计，采用滑动窗口算法计算每分钟请求数。当触发限流时，响应头会返回 X-RateLimit-Limit、X-RateLimit-Remaining 与 X-RateLimit-Reset 字段，便于客户端实现退避重试策略。

支持的文件格式

智压通压缩 API 覆盖文档、图像、视频、音频等多类文件格式，满足多样化压缩需求

文档格式

PDF、OFD、DOCX、XLSX、PPTX

图像格式

JPG、PNG、TIFF、GIF、BMP

视频格式

MP4、AVI、MOV

音频格式

MP3、WAV

各格式支持的压缩质量、输出选项与体积限制可能存在差异，具体以控制台与实际接口响应为准。如需支持其他格式，请联系商务团队沟通定制方案。

在线调试器

基于 Swagger UI 的在线 API 调试工具，即将上线

可视化调试

在线调试器提供可视化的接口参数填写与请求发送能力，无需编写代码即可快速验证接口行为与响应结构。

OpenAPI 3.0 规范

完整遵循 OpenAPI 3.0 规范，支持导出规范文件，可直接导入 Postman、Apifox 等工具进行本地调试。

即将上线

Swagger UI 在线调试器正在开发中，上线后您可直接在浏览器中体验完整的接口调试流程。在此之前可参考快速开始中的代码示例。

查看快速开始

立即开始使用 API

注册账号获取 API Key，将智压通压缩能力快速集成到您的应用中

快速开始了解 API 服务咨询商务