TinyCompress — Smart Image Compression
Overview
TinyCompress uses TinyPNG/Tinify's free web API to perform high-quality lossy compression on PNG, JPEG, and WebP images. No API key, no login, no payment required.
Key Features:
- Free — no API key or registration needed
- Supports PNG, JPEG, WebP formats
- Max 5MB per image, up to 20 images per batch
- Supports global server (tinypng.com) and China server (tinify.cn)
- Auto retry with exponential backoff on failure
- Rate-limit friendly with built-in request delays
- Typical compression: 50%~80% size reduction with near-zero visual quality loss
Prerequisites
- Python 3.6+ must be installed
- requests library:
pip install requests - Network access to
tinypng.comortinify.cn
Usage
1. Single Image Compression
When a user uploads or specifies one image:
python "{SKILL_DIR}/scripts/tiny_compress.py" compress "<image_path>"
Use China server for faster speed in China:
python "{SKILL_DIR}/scripts/tiny_compress.py" compress "<image_path>" --server cn
Output: generates <filename>_compressed.<ext> in the same directory.
2. Batch Compression
When a user provides multiple images:
python "{SKILL_DIR}/scripts/tiny_compress.py" compress "<file1>" "<file2>" ... --output-dir "<output_dir>"
3. Directory Compression
When a user specifies a directory:
python "{SKILL_DIR}/scripts/tiny_compress.py" compress-dir "<dir_path>" --output-dir "<output_dir>"
Add --recursive to include subdirectories.
4. Overwrite Mode
When user explicitly wants to replace original files:
python "{SKILL_DIR}/scripts/tiny_compress.py" compress "<file>" --overwrite
⚠️ Warning: Overwriting is irreversible. Always warn the user and suggest backup first.
Script Reference
scripts/tiny_compress.py
| Subcommand | Description |
|---|---|
compress <files...> |
Compress one or more image files |
compress-dir <dir> |
Compress all images in a directory |
| Parameter | Description | Default |
|---|---|---|
--output-dir <dir> |
Output directory | Same dir with _compressed suffix |
--server cn|global |
Server selection | global |
--overwrite |
Overwrite original files | false |
--recursive |
Recurse into subdirectories (compress-dir only) | false |
How it works:
- Upload endpoint:
POST https://tinypng.com/backend/opt/shrink(ortinify.cn/backend/opt/shrink) - Uploads raw image binary → server returns compression info + download URL → downloads compressed image
- Uses randomized User-Agent and X-Forwarded-For headers
- Serial processing with 1.5s delay between requests to avoid rate limiting
- Auto retry up to 3 times with exponential backoff
Output format (per image):
{
"success": true,
"file": "original_path",
"output": "output_path",
"original_size": 1234567,
"compressed_size": 345678,
"saved_bytes": 888889,
"saved_percent": 72.0
}
Examples
User: "Compress this image" (uploads photo.png)
Agent: runs compress on photo.png → returns photo_compressed.png with stats
User: "Compress all images in ./screenshots"
Agent: runs compress-dir ./screenshots → returns compressed versions
User: "Use China server, compress these 3 photos"
Agent: runs compress with --server cn on all 3 files
Limitations
- Max 5MB per image (TinyPNG web limit)
- Max 20 images per batch
- This uses TinyPNG's web frontend endpoint (not official API), may change without notice
- High-frequency requests may be temporarily rate-limited
- Does not support AVIF, GIF, BMP formats
- Uploaded images are auto-deleted from TinyPNG servers after 48 hours
Important Notes
- Privacy: Images are uploaded to TinyPNG servers for processing. Do NOT upload images containing sensitive/personal information.
- Fair Use: This method simulates web browser access. Use responsibly, avoid excessive automated calls.
- Network: Requires access to tinypng.com or tinify.cn.
- Alternative: For heavy batch processing, consider registering for TinyPNG's official API key (500 free compressions/month).