开发者

认证

在工作台创建 API Key，放进 Authorization 头。Key 只在创建时完整显示一次，服务端只保存散列。

Authorization: Bearer lp_live_a8f3k2…

快速开始

1. 上传图片，拿到任务号

   curl -X POST https://lubanpng.wizthink.cn/v1/images/compress \
     -H "Authorization: Bearer lp_live_…" \
     -F "file=@photo.png"
   
   { "code": 0, "msg": "success", "data": { "task_id": "550e8400-…" } }

2. 查询结果，带上 wait 让服务端最多等 30 秒

   curl "https://lubanpng.wizthink.cn/v1/images/compress/550e8400-…?wait=30" \
     -H "Authorization: Bearer lp_live_…"
   
   { "code": 0, "data": { "status": "completed",
       "original_size": 2516582, "compressed_size": 933241,
       "output_format": "jpeg", "quota_units": 1,
       "compressed_url": "/v1/images/download/550e8400-….jpg" } }

3. 下载产物，24 小时内有效

   curl -o photo.min.jpg "https://lubanpng.wizthink.cn/v1/images/download/550e8400-….jpg"

端点

格式转换

上传时带 convert 字段即可把静态图转成 png、jpeg、webp 或 avif。目标格式与原格式相同时按普通压缩处理，只计 1 次；不同则在压缩之外额外计 1 次。透明图转 JPEG 必须用 background 指定 #RRGGBB 背景色，否则任务失败并退回全部次数。动图（GIF、APNG、动态 WebP）暂不支持转换，只做保留动画的压缩。任务状态里的 target_format、output_format、quota_units 分别给出目标格式、实际产物格式与本次计次。

curl -X POST https://lubanpng.wizthink.cn/v1/images/compress \
  -H "Authorization: Bearer lp_live_…" \
  -F "file=@cutout.png" \
  -F "convert=jpeg" \
  -F "background=#ffffff"

{ "code": 0, "data": { "status": "completed", "target_format": "jpeg",
    "output_format": "jpeg", "quota_units": 2,
    "compressed_url": "/v1/images/download/550e8400-….jpg" } }

图片放大

POST /v1/images/upscale 接收静态 PNG 或 JPEG，按 scale（x2 / x4）放大，产物固定为 PNG。任务模型与压缩一致：上传拿到任务号，用同一组查询与下载端点取回结果。

curl -X POST https://lubanpng.wizthink.cn/v1/images/upscale \
  -H "Authorization: Bearer lp_live_…" \
  -F "file=@logo.png" \
  -F "scale=x2"

{ "code": 0, "msg": "success", "data": { "task_id": "550e8400-…" } }

curl "https://lubanpng.wizthink.cn/v1/images/compress/550e8400-…?wait=30" \
  -H "Authorization: Bearer lp_live_…"

{ "code": 0, "data": { "status": "completed", "kind": "upscale",
    "scale": "x2", "original_size": 398829, "compressed_size": 1194351,
    "output_format": "png", "quota_units": 1, "no_gain": false,
    "compressed_url": "/v1/images/download/550e8400-….png" } }

放大在 GPU 上单飞：同一时刻只处理一个任务，繁忙时排队（队列深度上限 10，超限返回 429 并带 Retry-After 与 queue_depth）；放大服务不可用时提交直接返回 503。

成功放大计 1 次，与压缩共用同一份额度；失败、超时、格式不符或超出上限都不计次。放大产物必然比原图大，因此不适用压缩的「更小才计次」规则；任务状态里 quota_units 为实扣次数，no_gain 仅在失败时为 true。

额度与错误

每个响应都带三个额度头，只有真正产出更小文件才计一次，失败或压缩后没有变小自动退回（未转换时保留原图；显式转换即使产物不小于原图也会返回转换结果，但不计次）；格式转换额外计 1 次。任务状态里的 quota_units 在非终态是预扣次数（预计），终态是实扣次数；no_gain 为 true 当且仅当本次未计次。

X-Quota-Limit: 50
X-Quota-Remaining: 46
X-Quota-Reset: 2026-10-01T00:00:00Z

For AI agents

机器可读入口：llms.txt 汇总双能力、额度与接入通道；OpenAPI 给出完整契约。

llms.txt · 机器可读摘要

OpenAPI · 完整契约

CLI

走同一套 API 与额度。登录一次，Key 存在本机用户配置目录（macOS / Linux 为 ~/.config/lubanpng，Windows 为 %APPDATA%\lubanpng）。

npm i -g lubanpng

Node 24+，macOS / Linux / Windows。

$ lubanpng login
  粘贴你的 API Key: lp_live_…
  已登录 zibin@example.com · 本月剩余 46 次

$ lubanpng compress ./images --out ./dist --recursive
  photo_banner.jpg   2.40 MB → 0.89 MB   -63%
  logo@2x.png         312 KB →   96 KB   -69%
  sticker_wave.gif   1.10 MB → 0.71 MB   -36%
  本次 3 张，节省 2.11 MB，本月剩余 43 次

$ lubanpng compress ./hero.png --convert webp
  hero.png           1.20 MB → 0.31 MB   -74%   → hero.webp
  本次 1 张，节省 0.89 MB，本月剩余 41 次，1 张已转换

$ lubanpng usage
  免费套餐 · 本月已用 7 / 50 · 10 月 1 日重置

常见问题