\r \r

TinyCompress — Smart Image Compression\r

\r \x3Cdescription>\r Use when: compressing images, optimizing image file size, reducing image size, tinypng, tinify, compress image, compress png, compress jpeg, compress webp, image optimization, shrink image, 压缩图片, 图片压缩, 图片优化, 图片瘦身, 减小图片体积\r NOT for: image resizing/cropping, format conversion, image editing, video compression\r \x3C/description>\r \r

Overview\r

\r 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.\r \r Key Features:\r

• Free — no API key or registration needed\r
• Supports PNG, JPEG, WebP formats\r
• Max 5MB per image, up to 20 images per batch\r
• Supports global server (tinypng.com) and China server (tinify.cn)\r
• Auto retry with exponential backoff on failure\r
• Rate-limit friendly with built-in request delays\r
• Typical compression: 50%~80% size reduction with near-zero visual quality loss\r \r

Prerequisites\r

\r

• Python 3.6+ must be installed\r
• requests library: pip install requests\r
• Network access to tinypng.com or tinify.cn\r \r

Usage\r

\r

1. Single Image Compression\r

\r When a user uploads or specifies one image:\r \r

python "{SKILL_DIR}/scripts/tiny_compress.py" compress "\x3Cimage_path>"\r
```\r
\r
Use China server for faster speed in China:\r
```bash\r
python "{SKILL_DIR}/scripts/tiny_compress.py" compress "\x3Cimage_path>" --server cn\r
```\r
\r
Output: generates `\x3Cfilename>_compressed.\x3Cext>` in the same directory.\r
\r
### 2. Batch Compression\r
\r
When a user provides multiple images:\r
\r
```bash\r
python "{SKILL_DIR}/scripts/tiny_compress.py" compress "\x3Cfile1>" "\x3Cfile2>" ... --output-dir "\x3Coutput_dir>"\r
```\r
\r
### 3. Directory Compression\r
\r
When a user specifies a directory:\r
\r
```bash\r
python "{SKILL_DIR}/scripts/tiny_compress.py" compress-dir "\x3Cdir_path>" --output-dir "\x3Coutput_dir>"\r
```\r
\r
Add `--recursive` to include subdirectories.\r
\r
### 4. Overwrite Mode\r
\r
When user explicitly wants to replace original files:\r
\r
```bash\r
python "{SKILL_DIR}/scripts/tiny_compress.py" compress "\x3Cfile>" --overwrite\r
```\r
\r
⚠️ **Warning:** Overwriting is irreversible. Always warn the user and suggest backup first.\r
\r
## Script Reference\r
\r
### scripts/tiny_compress.py\r
\r
| Subcommand | Description |\r
|------------|-------------|\r
| `compress \x3Cfiles...>` | Compress one or more image files |\r
| `compress-dir \x3Cdir>` | Compress all images in a directory |\r
\r
| Parameter | Description | Default |\r
|-----------|-------------|---------|\r
| `--output-dir \x3Cdir>` | Output directory | Same dir with `_compressed` suffix |\r
| `--server cn\|global` | Server selection | `global` |\r
| `--overwrite` | Overwrite original files | `false` |\r
| `--recursive` | Recurse into subdirectories (compress-dir only) | `false` |\r
\r
**How it works:**\r
- Upload endpoint: `POST https://tinypng.com/backend/opt/shrink` (or `tinify.cn/backend/opt/shrink`)\r
- Uploads raw image binary → server returns compression info + download URL → downloads compressed image\r
- Uses randomized User-Agent and X-Forwarded-For headers\r
- Serial processing with 1.5s delay between requests to avoid rate limiting\r
- Auto retry up to 3 times with exponential backoff\r
\r
**Output format (per image):**\r
```json\r
{\r
  "success": true,\r
  "file": "original_path",\r
  "output": "output_path",\r
  "original_size": 1234567,\r
  "compressed_size": 345678,\r
  "saved_bytes": 888889,\r
  "saved_percent": 72.0\r
}\r
```\r
\r
## Examples\r
\r
```\r
User: "Compress this image" (uploads photo.png)\r
Agent: runs compress on photo.png → returns photo_compressed.png with stats\r
\r
User: "Compress all images in ./screenshots"\r
Agent: runs compress-dir ./screenshots → returns compressed versions\r
\r
User: "Use China server, compress these 3 photos"\r
Agent: runs compress with --server cn on all 3 files\r
```\r
\r
## Limitations\r
\r
- Max 5MB per image (TinyPNG web limit)\r
- Max 20 images per batch\r
- This uses TinyPNG's web frontend endpoint (not official API), may change without notice\r
- High-frequency requests may be temporarily rate-limited\r
- Does not support AVIF, GIF, BMP formats\r
- Uploaded images are auto-deleted from TinyPNG servers after 48 hours\r
\r
## Important Notes\r
\r
- **Privacy:** Images are uploaded to TinyPNG servers for processing. Do NOT upload images containing sensitive/personal information.\r
- **Fair Use:** This method simulates web browser access. Use responsibly, avoid excessive automated calls.\r
- **Network:** Requires access to tinypng.com or tinify.cn.\r
- **Alternative:** For heavy batch processing, consider registering for TinyPNG's official API key (500 free compressions/month).\r