結論先行：SmartSlim Server 提供RESTful API，含むアップロード圧縮、バッチ量圧縮、状态查询、回调通知4大接口，サポートAPI Key和Bearer Token2種類认证方式。单ファイルアップロード圧縮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 | 圧縮完成后主动通知 | 异步推送 |
认证方式分2種類：API Key认证適したサービス端调用，Bearer Token认证適した前端调用。下表比較2種類认证方式的特点。
| 认证方式 | 请求头 | 有效期 | 適用シナリオ | 安全性 |
|---|---|---|---|---|
| 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サポート2種類认证方式：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%。
覚えておくべき3つのポイント：一是50MB以下同步返回結果，以上异步用任务ID查询；二是限流429要実現指数退避重试，别硬刷；三是大ファイル用分ブロックアップロード接口，5MB一ブロック分バッチアップロード。选に対して接口和パラメータ，圧縮API的调用其实很簡単。如果你更倾向ローカルSDK集成而非HTTP调用，を参照してください圧縮SDK集成指南。
ファイルを圧縮してみませんか？SmartSlimを試す
独自開発のRust圧縮エンジンに基づき、PDF/画像/動画/Office/OFDなど10分野40以上の形式に対応。ローカル圧縮でデータは外部に送信されません。