API Docs - Complete Compression API Reference | UGLYPEAR DATA Developer Center

Authentication

The SmartSlim Compression API uses Bearer Token authentication

Bearer Token

The API Key is passed via the HTTP request header Authorization in the format Bearer YOUR_API_KEY. All API requests must include this header; missing or invalid keys will return a 401 error.

Transport Security

All API requests are transmitted over HTTPS encrypted connections. Do not use plain HTTP protocol to call the API, ensuring the security of your API Key and file data during transmission.

API Key Management

API Keys can be viewed, reset, and disabled in the Application Management section of the Developer Console. We recommend creating separate applications for different environments (development/staging/production) for easier isolation and auditing.

# Authentication request header example
Authorization: Bearer YOUR_API_KEY

Endpoint List

The SmartSlim Compression API provides complete endpoints for file compression, task management, batch processing, and usage statistics

POST /v1/compress

File Compression: Upload a single file and perform compression.

file (required): The file to compress
quality: Compression quality, options: low / medium / high
format: Output format
password (optional): Encryption password for compressed files

GET /v1/tasks/{task_id}

Query Task Status: Retrieve the current status and result information of a compression task by its task ID.

Returns status: pending / processing / completed / failed

GET /v1/tasks/{task_id}/download

Download Compressed File: After a task is completed, download the compressed result file via this endpoint. Returns a file stream.

POST /v1/batch/compress

Batch Compression: Upload multiple files at once for batch compression processing.

files[] (required): Array of files to compress
quality: Compression quality
format: Output format
callback_url (optional): Callback URL for task completion notification

GET /v1/usage

Query Usage Statistics: Retrieve usage data for the current account, including this month's API call count, total compressed file size, storage usage, and more.

DELETE /v1/tasks/{task_id}

Delete Task: Delete a specified compression task and its result files by task ID, freeing up storage space.

File Compression Endpoint Request Example

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

(file binary content)
------FormBoundary
Content-Disposition: form-data; name="quality"

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

pdf
------FormBoundary--

Task Status Query Response Example

{
  "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"
}

Error Code Reference

HTTP status codes and their meanings that may be returned during API calls, useful for troubleshooting and exception handling

HTTP Status Code	Name	Description
200	Success	Request processed successfully, returning expected result data.
400	Bad Request	Request parameters are missing, incorrectly formatted, or exceed limits. Please check the request body and parameters.
401	Unauthorized	Authorization header is missing, API Key is invalid or expired. Please obtain a valid key.
403	Forbidden	The current API Key does not have permission to access the resource or perform the operation. Please verify your plan permissions and resource ownership.
429	Too Many Requests	Request frequency exceeds the rate limit threshold for the current plan. Please reduce the call frequency or upgrade your plan.
500	Internal Server Error	An exception occurred during server-side processing. Please retry later or contact technical support.
503	Service Unavailable	The service is under maintenance or temporarily overloaded. Please retry later.

Error Response Example

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded, current plan limit is 60 requests/minute",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

Rate Limiting Policy

Different plans have different request frequency limits. Exceeding the limit returns a 429 error. Please choose a plan that fits your business volume

10

Free Plan
requests/minute

60

Basic Plan
requests/minute

300

Pro Plan
requests/minute

Unlimited

Enterprise Plan
Configurable on demand

Rate limiting is measured per API Key using a sliding window algorithm to count requests per minute. When rate limited, the response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset fields to help clients implement backoff and retry strategies.

Supported File Formats

The SmartSlim Compression API covers document, image, video, and audio file formats to meet diverse compression needs

Document Formats

PDF, OFD, DOCX, XLSX, PPTX

Image Formats

JPG, PNG, TIFF, GIF, BMP

Video Formats

MP4, AVI, MOV

Audio Formats

MP3, WAV

Supported compression quality, output options, and file size limits may vary by format. Please refer to the console and actual API responses for details. To request support for additional formats, please contact our sales team to discuss custom solutions.

Online Debugger

Online API debugging tool based on Swagger UI, coming soon

Visual Debugging

The online debugger provides a visual interface for filling in endpoint parameters and sending requests, allowing you to quickly verify endpoint behavior and response structure without writing code.

OpenAPI 3.0 Specification

Fully compliant with the OpenAPI 3.0 specification, supporting spec file export. You can import it directly into tools like Postman or Apifox for local debugging.

Coming Soon

The Swagger UI online debugger is under development. Once launched, you will be able to experience the complete API debugging workflow directly in your browser. In the meantime, please refer to the code examples in the Quick Start guide.

View Quick Start

API Docs - Complete Compression API Reference