How to generate a BlurHash placeholder string for an image

POST an image URL to /v1/image/blurhash. It returns the BlurHash string, a short text you can store next to the image and decode in the browser into a blurred preview.

Request

x_components (default 4) and y_components (default 3) are 1 to 9; more components keep more detail and make a longer string. The output is the published woltapp BlurHash algorithm, identical to the reference package. 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/blurhash \
  -H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
  -d '{"url": "https://raw.githubusercontent.com/ianare/exif-samples/master/jpg/gps/DSCN0010.jpg"}'

Response

Response (example from the API spec, trimmed)

{
  "operation": "blurhash",
  "input": {
    "format": "jpeg",
    "width": 640,
    "height": 480,
    "bytes": 161713,
    "frames": 1,
    "animated": false,
    "has_alpha": false
  },
  "source_url": "https://raw.githubusercontent.com/ianare/exif-samples/master/jpg…",
  "final_url": "https://raw.githubusercontent.com/ianare/exif-samples/master/jpg…",
  "blurhash": "LRIN+zx[Rms:~nxajIxatRxajHxt",
  "x_components": 4,
  "y_components": 3,
  "notes": [],
  "source": {
    "library": "Pillow",
    "license": "MIT-CMU (HPND)",
    "url": "https://python-pillow.org"
  }
}

Limits and caveats

Decoding is yours. The API produces the string only. Decode it client side with a BlurHash library and draw it on a small canvas.

A placeholder, not a thumbnail. It is a rough blur of colours. For a real small image use the thumbnail endpoint.

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.

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_blurhash at https://tanod.dev/mcp, where the free tier is automatic.

All endpoints →

Related guides: How to generate several thumbnail sizes from one image with an API, How to extract the dominant colors and palette of an image with an API, How to resize an image from a URL with an API. Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.