Compression API Guide: RESTful Interface Documentation

BLUF: SmartSlim Server provides a RESTful API with 4 main interfaces — upload compression, batch compression, status query, and callback notification — supporting API Key and Bearer Token authentication. Single-file upload compression of a 100MB PDF completes in about 8s, and batch compression of 100 files takes about 12s. Default rate limit is 60 requests per minute, with Enterprise edition supporting up to 300. This article provides parameter reference tables for all 4 interfaces, Python/JavaScript/curl examples, and error handling strategies. Below, we start with an API overview and detail each interface.

If you need local SDK integration instead of HTTP API calls, we recommend readingCompression SDK Integration Guide: Python/Java/C# Multi-Language Calls。

1. API Overview

SmartSlim Server's RESTful API is built on the FastAPI framework. All interfaces return JSON data and support multipart/form-data file uploads. The API base path is /api/v1/, and all requests must include authentication information.

Authentication has two methods: API Key for server-side calls, Bearer Token for frontend calls. The table below compares the two.

2. Interface Parameter Reference

1. Upload Compression Interface

The upload compression interface receives a single file and returns compression results. Files under 50MB synchronously return a download link for the compressed file; files over 50MB asynchronously return a task ID.

2. Batch Compression Interface

The batch compression interface receives multiple files, processes them asynchronously, and returns a batch task ID. Supports specifying concurrency, with maximum concurrency limited by license.

3. Status Query Interface

The status query interface retrieves the current status and results of an async compression task via task ID.

3. Code Examples in Three Languages

Below are call examples in curl, Python, and JavaScript, all demonstrating upload compression of a single PDF file.

4. Rate Limiting and Error Handling

The API has comprehensive rate limiting and error handling mechanisms. Understanding HTTP status codes and error codes is essential for writing robust calling code.

Rate limiting details: default 60 requests per minute, 10 concurrent per second; Enterprise edition 300 per minute, 30 concurrent per second. Exceeding limits returns 429, with response headers containing X-RateLimit-Remaining (remaining count) and X-RateLimit-Reset (reset timestamp). Clients should implement exponential backoff retry: wait 1s after receiving 429, then 2s, then 4s, with a maximum of 3 retries.

If you need to understand the underlying design of compression task queues, seeCompression Task Queue Design. If you need to deploy API services via Docker, seeDocker Compression Service Deployment。

5. FAQ

Q1: How to authenticate compression API calls?

SmartSlim Server's compression API supports two authentication methods: API Key authentication (pass the key in the X-API-Key header, suitable for server-side calls) and Bearer Token authentication (pass a JWT Token in the Authorization header, suitable for frontend calls). API Keys are permanent but can be revoked at any time, while Tokens are valid for 24 hours and require periodic refresh. For production environments, API Key is recommended for its simplicity and reliability.

Q2: Which file formats does the compression API support?

SmartSlim Server API supports PDF, images (jpg/jpeg/tif), and OFD formats, with a 1GB single-file limit. SmartSlim Cloud API supports all 10 categories and 40+ formats (including video, audio, Office documents, etc.), with a 10GB single-file limit. Specify the file type via the format parameter when calling; if omitted, it is auto-detected. Note that the Server edition only supports PDF/image/OFD; full format support requires the Cloud edition.

Q3: Does the compression API have rate limits?

Rate limiting protects service stability. Default limits: 60 requests per minute, 10 concurrent per second. Exceeding limits returns a 429 status code, with response headers containing X-RateLimit-Remaining and X-RateLimit-Reset fields. Enterprise edition can be increased to 300 requests per minute and 30 concurrent per second. Clients are recommended to implement exponential backoff retry — wait 1-2-4 seconds incrementally after receiving 429.

Q4: How does the compression API handle large files?

For large files (over 50MB), use the chunked upload interface — split the file into multiple 5MB chunks, upload all, then notify to merge and compress. After compression completes, retrieve results via callback notification or polling the status query interface. Large file compression is asynchronous and does not block API calls. A 100MB PDF takes about 8s, a 1GB video takes about 90s, and a download link is automatically generated upon completion.

Summary

SmartSlim Server's RESTful API provides 4 main interfaces — upload compression, batch compression, status query, and callback notification — covering all scenarios from single files to batch processing. Two authentication options: API Key for server-side, Bearer Token for frontend. Clear rate limiting: default 60 per minute, Enterprise 300, with 429 status code and exponential backoff retry. An 80MB scanned PDF compresses to 8.2MB in just 6.5s, a 89.8% compression ratio.

Remember three points: first, files under 50MB return results synchronously, while larger files use async task IDs for querying; second, implement exponential backoff retry for 429 rate limits — don't just retry aggressively; third, use the chunked upload interface for large files, splitting into 5MB chunks. With the right interface and parameters, compression API calls are straightforward. If you prefer local SDK integration over HTTP calls, see the Compression SDK Integration Guide.