How to generate a BlurHash placeholder string for an image

Updated 2026-11-10

Use when an image needs a compact BlurHash string to show as a placeholder while it loads.

From an MCP client, add https://tanod.dev/mcp and call image_blurhash; its free daily calls are applied automatically, no key or signup.

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.

Placeholder only. 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, Polygon, Solana, BNB Chain or Arbitrum 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 →

Use it from Claude without writing code: in claude.ai or Claude Desktop, add https://tanod.dev/mcp/images?via=blurhash-api as a custom connector (steps), then ask in plain words, for example "Make a BlurHash placeholder for this image." The free daily allowance is applied automatically over MCP. Beyond it a call needs an x402 payment, which these clients can make.

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.