How to generate several thumbnail sizes from one image with an API

POST an image URL and a list of sizes to /v1/image/thumbnail. It returns one thumbnail per size in images.

Request

sizes is 1 to 8 entries of {width, height}, each up to 4096. fit is cover (centre crop with gravity, default) or contain. Not upscaled unless upscale is true, so a thumbnail may come back smaller than requested (see the second entry in the example). Input is a public image URL (up to 10 MB) or image_base64 (up to 10 MB decoded; a data:image/...;base64, prefix is fine).

curl, using the free tier

curl -s -X POST https://tanod.dev/v1/image/thumbnail \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://tanod.dev/icon.png", "sizes": [{"width": 128, "height": 128}, {"width": 320, "height": 180}]}'

The file comes back as base64 in the JSON. To save it, pipe the response through jq and base64:

save the result to a file

curl -s -X POST https://tanod.dev/v1/image/thumbnail \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://tanod.dev/icon.png", "sizes": [{"width": 128, "height": 128}, {"width": 320, "height": 180}]}' \
  | jq -r '.images[0].data_base64' | base64 -d > thumb-128.png

Response

Response (example from the API spec, trimmed)

{
  "operation": "thumbnail",
  "input": {
    "format": "png",
    "width": 256,
    "height": 256,
    "bytes": 2183,
    "frames": 1,
    "animated": false,
    "has_alpha": true
  },
  "source_url": "https://tanod.dev/icon.png",
  "final_url": "https://tanod.dev/icon.png",
  "images": [
    {
      "requested": {
        "width": 128,
        "height": 128
      },
      "format": "png",
      "content_type": "image/png",
      "bytes": 3265,
      "width": 128,
      "height": 128,
      "data_base64": "iVBORw0KGgoAAAAN"
    },
    {
      "requested": {
        "width": 320,
        "height": 180
      },
      "format": "png",
      "content_type": "image/png",
      "bytes": 581,
      "width": 256,
      "height": 144,
      "data_base64": "iVBORw0KGgoAAAAN"
    }
  ],
  "total_bytes": 3846,
  "notes": [],
  "source": {
    "library": "Pillow",
    "license": "MIT-CMU (HPND)",
    "url": "https://python-pillow.org"
  }
}

Limits and caveats

Shared output cap. The 15 MB output limit covers all thumbnails together.

Crop is positional. cover crops around the chosen gravity; it does not detect subjects.

Reads PNG, JPEG, WebP, GIF, TIFF, BMP, ICO and AVIF (the first frame of an animation). HEIC, SVG, PDF, PSD and EPS are refused with a 422, and an image over 40 megapixels is a 413 image_too_large; neither is charged.

Metadata is not copied. EXIF, GPS, XMP and IPTC metadata are not carried into output images. Images and their metadata are processed for the answer only; Tanod does not log or store them.

Price and free allowance

USD 0.002 per call, paid in USDC on Base with x402. 3 free calls per IP per UTC day with the header X-Tanod-Free: 1. The pool is shared by every image operation. MCP tool: image_thumbnail at https://tanod.dev/mcp, where the free tier is automatic.

All endpoints →

Related guides: How to resize an image from a URL with an API, How to generate a BlurHash placeholder string for an image, How to generate a favicon set (ICO, PNG, Apple touch icon) from an image. Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.