Developers

Authentication

Create an API key in the dashboard and put it in the Authorization header. The key is shown in full only once — the server stores just its hash.

Authorization: Bearer lp_live_a8f3k2…

Quick start

1. Upload an image and get a task id

   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. Poll the result, passing wait so the server holds for up to 30 seconds

   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. Download the result — valid for 24 hours

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

Endpoints

Format conversion

Pass convert when uploading to turn a static image into png, jpeg, webp or avif. Converting to the source format is treated as a plain compression and counts 1 run; converting to a different format costs 1 extra run. Transparent images converted to JPEG must set a #RRGGBB background colour, otherwise the task fails and every run is refunded. Animations (GIF, APNG, animated WebP) can't be converted yet — they are compressed with their animation preserved. In the task status, target_format, output_format and quota_units report the target format, the actual output format and the runs counted.

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

Upscaling

POST /v1/images/upscale takes a static PNG or JPEG and enlarges it by scale (x2 or x4); the output is always PNG. The task model matches compression: upload to get a task id, then use the same polling and download endpoints as compression.

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

Upscaling is single-flight on the GPU: one job at a time, with uploads queuing while it is busy (queue depth limit 10 — beyond that the upload returns 429 with Retry-After and queue_depth). If the upscaler is unreachable, the upload returns 503.

A successful upscale costs 1 run from the same pool as compression; failures, timeouts, unsupported formats and over-limit inputs are never charged. The output is always larger than the input, so the compression rule of charging only smaller output does not apply; in the task status quota_units is the amount charged and no_gain is true only for a failed upscale.

Quota & errors

Every response carries three quota headers. A run is counted only when the output really gets smaller; failures or results that don't shrink are refunded automatically (the original is kept unless you convert, and an explicit conversion still returns the converted file even when it isn't smaller, but costs nothing); format conversion costs 1 extra run. In the task status, quota_units is the reserved estimate while the task is in flight and the runs actually charged once it reaches a terminal state; no_gain is true exactly when the task was not counted.

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

For AI agents

Machine-readable entry points: llms.txt summarises both capabilities, the quota and the access channels; the OpenAPI document gives the full contract.

llms.txt · machine-readable summary

OpenAPI · full contract

CLI

It speaks the same API and draws on the same quota. Sign in once and the key is stored in your user config directory (macOS / Linux: ~/.config/lubanpng, Windows: %APPDATA%\lubanpng).

npm i -g lubanpng

Node 24+, macOS / Linux / Windows.

$ lubanpng login
  Paste your API key: lp_live_…
  Signed in as zibin@example.com · 46 runs left this month

$ 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 images, saved 2.11 MB, 43 runs left this month

$ lubanpng compress ./hero.png --convert webp
  hero.png           1.20 MB → 0.31 MB   -74%   → hero.webp
  1 image, saved 0.89 MB, 41 runs left this month, 1 converted

$ lubanpng usage
  Free plan · used 7 / 50 this month · resets Oct 1

FAQ