TinyPNG 批量压缩工具

这是一个基于 Tinify/TinyPNG Python SDK 的批量图片压缩和格式转换工具。它提供图形界面和命令行两种使用方式，支持多个 API Key 接力使用、官方额度同步、批量格式转换、递归处理目录、HTTP/SOCKS5 代理，以及 Windows 二进制打包分发。

功能

• GUI 图形界面，适合日常批量处理图片。
• CLI 命令行入口，适合脚本化或自动化处理。
• 支持多个 Tinify API Key，每个 Key 默认每月 500 张额度。
• 支持处理前同步官方本月已用额度。
• 支持 PNG、JPG/JPEG、WebP、AVIF 输入。
• 支持输出源格式、PNG、JPEG、WebP、AVIF，也可以一次输出全部格式。
• 支持递归扫描目录。
• 支持覆盖已有输出文件或跳过已有文件。
• 支持试运行，只预览处理计划，不调用 Tinify API。
• 支持 HTTP 代理和 SOCKS5 代理。

目录说明

C:\dev\py\tinypng
├─ source\                 默认输入目录，把待处理图片放这里
├─ optimized\              默认输出目录，运行后自动生成
├─ tinypng_gui.py          GUI 程序
├─ tinypng_balancer.py     命令行和核心处理逻辑
├─ run_gui.bat             双击启动 GUI
├─ tinify_keys.sample.json API Key 配置模板
├─ tinify_keys.json        实际 API Key 配置文件，本地使用，不提交 Git
├─ tinify_usage.json       本月额度缓存文件，本地使用，不提交 Git
├─ pyproject.toml          uv 项目依赖配置
└─ uv.lock                 uv 锁定文件

打包后使用 --onedir 文件夹版时，默认目录会改为可执行文件所在目录：

dist\tinypng-gui
├─ tinypng-gui.exe
├─ _internal\
├─ source\
├─ optimized\
├─ tinify_keys.json
└─ tinify_usage.json

source、optimized 和 JSON 配置文件不会放到 _internal 里。

安装依赖

项目使用 uv 管理依赖：

cd C:\dev\py\tinypng
uv sync

主要依赖：

• tinify：TinyPNG 官方 Python SDK。
• requests[socks]：为 HTTP/SOCKS5 代理提供支持。

启动 GUI

推荐直接双击：

run_gui.bat

也可以在命令行运行：

cd C:\dev\py\tinypng
uv run tinypng_gui.py

配置 API Key

打开 GUI 后点击 填写 API Key。

支持一行一个：

KEY_1
KEY_2
KEY_3

也支持用逗号、分号或空格分隔。保存后会生成 tinify_keys.json，主界面的“配置文件”会自动指向该文件。

配置文件格式示例：

{
  "api_keys": [
    {
      "key": "YOUR_TINIFY_API_KEY_1",
      "monthly_limit": 500,
      "name": "账号-1"
    },
    {
      "key": "YOUR_TINIFY_API_KEY_2",
      "monthly_limit": 500,
      "name": "账号-2"
    }
  ],
  "proxy": null
}

不要把真实 API Key 写入 tinify_keys.sample.json，它只作为模板示例。

代理格式

不需要代理时留空。

HTTP 代理：

http://127.0.0.1:7890

SOCKS5 代理：

socks5://127.0.0.1:1080

带账号密码：

http://username:password@127.0.0.1:7890
socks5://username:password@127.0.0.1:1080

常见代理软件的 HTTP 端口可能是 7890、10809，SOCKS5 端口可能是 1080、10808。以代理软件里实际显示的端口为准。

GUI 使用流程

1. 把图片放入 source 文件夹，或在界面中选择其他输入目录。
2. 点击 填写 API Key，粘贴一个或多个 API Key 并保存。
3. 如需代理，在代理输入框填写 HTTP 或 SOCKS5 地址。
4. 确认输出目录，默认是 optimized。
5. 按需选择转换格式、递归扫描、覆盖输出、试运行、同步官方额度等选项。
6. 点击 开始处理。

转换格式

转换格式 默认选择 源格式 和 webp。

可选值：

• 源格式：只压缩，不改变格式。
• png：输出 PNG。
• jpeg / jpg：输出 JPEG。
• webp：输出 WebP。
• avif：输出 AVIF。
• all：命令行专用，一次输出源格式、PNG、JPEG、WebP、AVIF。

注意：转换、缩放等 Tinify API 操作可能会消耗压缩额度。一次输出多个格式时，每张输入图片会产生多个输出，额度消耗也会相应增加。

额度同步

GUI 默认勾选 同步官方额度。

处理开始前，程序会对每个 API Key 调用官方 SDK 的 tinify.validate()，然后读取 tinify.compression_count，同步该 Key 本月已经使用的数量。

同步后的额度会写入：

tinify_usage.json

后续每次处理成功后，程序也会读取 SDK 更新后的 tinify.compression_count 并回写本地用量缓存。

命令行用法

压缩目录：

uv run tinypng_balancer.py source -o optimized

递归压缩：

uv run tinypng_balancer.py source -o optimized --recursive

转换为 WebP：

uv run tinypng_balancer.py source -o optimized --convert webp

同时输出源格式和 WebP：

uv run tinypng_balancer.py source -o optimized --convert source --convert webp

输出全部格式：

uv run tinypng_balancer.py source -o optimized --convert all

缩放：

uv run tinypng_balancer.py source -o optimized --resize-method fit --width 1200 --height 1200

试运行：

uv run tinypng_balancer.py source -o optimized --dry-run

跳过启动前官方额度同步：

uv run tinypng_balancer.py source -o optimized --no-sync-usage

指定配置和用量文件：

uv run tinypng_balancer.py source -o optimized --config tinify_keys.json --state tinify_usage.json

生成配置模板：

uv run tinypng_balancer.py --init-config tinify_keys.json

打包 Windows 二进制

推荐打包为 onedir 文件夹版：

uv run --with pyinstaller pyinstaller --noconfirm --clean --onedir --windowed --name tinypng-gui --collect-data tinify --add-data "tinify_keys.sample.json;." tinypng_gui.py

输出目录：

dist\tinypng-gui\

启动文件：

dist\tinypng-gui\tinypng-gui.exe

分发时需要把整个 dist\tinypng-gui\ 文件夹一起发出去，因为 _internal\ 里包含运行依赖。

不推荐日常使用 --onefile 单文件版。单文件版启动时会先解压依赖到系统临时目录；文件夹版不会把依赖释放到 Temp，路径也更容易管理。

Git 忽略

以下文件通常不需要提交：

tinify_keys.json
tinify_usage.json
optimized
source
build/
dist/
*.spec
*.exe

pyinstaller 只在打包时临时安装和使用，不需要作为项目依赖提交。

常见问题

提示 No module named 'tinify'

请使用 uv run 启动：

uv run tinypng_gui.py

或者双击 run_gui.bat。

填写 socks5:// 代理后提示缺少 SOCKS 支持

确认已经安装 SOCKS 依赖：

uv sync

如果是旧环境，可以重新添加依赖：

uv add requests[socks]

然后重新打包二进制。

打包版路径指向 _internal

请使用新版代码重新打包。GUI 会在打包环境中使用 tinypng-gui.exe 所在目录作为默认目录，不会把 source、optimized、tinify_keys.json 放进 _internal。

没有找到图片

确认图片放在输入目录中。支持的扩展名包括：

.png .jpg .jpeg .webp .avif

API Key 不可用

检查 tinify_keys.json 中是否写入了真实 Key。模板中的 YOUR_TINIFY_API_KEY_1 不能直接使用。

全部格式输出时额度消耗变多

这是正常的。因为每张图片会分别转换为多个格式，每个输出都可能消耗 Tinify 额度。