API

One URL is the whole API

Every image is a GET request you can paste into a browser, an <img> tag, or a build script. No key, no signup.

Quick start

$ curl -O "https://png.quran.ws/api/v1/image/2/255.png?layout=fit&aspect=post&width=3000"

surah 2 · ayah 255 · 4:5 portrait · 3000 px wide · transparent

Path

Parameters

layout=mushaf reproduces the plate: every word keeps the x it has on the printed page and the baseline it sits on, so the image is the mushaf itself, cropped to your selection. There is nothing to align — the printed lines are justified to one shared text block, and that relationship is part of the artwork. layout=fit repacks the same word artwork into lines that fill the requested aspect, spreading each line but the last flush to both edges. Neither ever scales or stretches a letter — justification moves the gaps between words, never the words themselves, and a line that would have to stretch more than three times its natural spacing is left ragged rather than pulled apart.

Metadata

Errors say what to fix

GET /api/v1/image/2/999.png   → 400
{ "error": "surah 2 has 286 ayahs, got 999-999" }

Limits

120 requests per minute per IP. Rendered images are cached server-side and carry an ETag, so a page that hotlinks the same ayah costs one render, ever — a site that embeds the same few ayahs will never come close to the limit. If you need more than that for something real, get in touch.

Plain URLs are cached for five minutes and then revalidated, so a fix to the layout reaches you. Add v=2 to pin the current renderer: that URL is then immutable and safe to cache for a year, and it will keep drawing exactly what it draws today.

Artwork: King Fahd Glorious Qur'an Printing Complex, Madani mushaf V4 (1441H). Licence and provenance.