Quran PNG

A URL in, an image out. Any range of ayat as a transparent PNG, an SVG or a print-ready PDF of the actual printed muṣḥaf — no font to install, no shaping engine, no key.

What this is

Quran PNG is a tool, not one of the eight building blocks. It is a service built on the artwork that Quran SVG Elements publishes, and it exists to be the shortest possible path from a reference to a picture of that reference.

Reach for it when the destination cannot lay out Arabic text for you: Canva, Figma, Illustrator, Keynote, a PDF generator, an email template, a social card. Nothing in the response is typeset. Every word is vector artwork lifted from the printed plate and moved onto a new canvas.

Get an image now

curl -o kursi.png \
  "https://png.quran.ws/api/v1/image/2/255.png?layout=fit&aspect=wide&width=1400"

The same URL works as an <img> source. Access-Control-Allow-Origin: * is set, so a browser can fetch it directly.

<img
  src="https://png.quran.ws/api/v1/image/2/255.png?layout=fit&aspect=wide&width=1400"
  alt="Surah 2, ayah 255, from the printed Madani muṣḥaf"
/>

That is the whole API surface for the common case.

Addressing an image

GET /api/v1/image/{surah}/{range}.{png|svg|pdf}

surah is 1–114. Anything outside that returns 400 with {"error":"surah must be 1..114"}.

range takes three forms:

Ranges do not cross a surah boundary. A range beyond the end of the surah is rejected rather than clamped: /2/300.png returns 400 with {"error":"surah 2 has 286 ayahs, got 300-300"}.

There is a second, equivalent form for callers who would rather not build a path:

GET /api/v1/image?surah=112&from=1&to=4&format=svg

The format is taken from the extension, or from format= when there is no extension. png, svg and pdf are the only three; anything else returns 400.

The two layouts

Because the shapes are only ever moved, never scaled or stretched, there are two ways to lay a range out. layout=mushaf is the default.

Justification in fit moves the gaps only. The printed muṣḥaf stretches letters to justify a line, and doing that here would distort the artwork, so a line that would need more than three times its natural word spacing is left ragged instead.

aspect accepts the five named ratios or any explicit w:h:

# a named ratio
curl -o story.png "https://png.quran.ws/api/v1/image/112/1-.png?layout=fit&aspect=story"

# an explicit one — anything matching w:h
curl -o odd.png "https://png.quran.ws/api/v1/image/112/1-.png?layout=fit&aspect=2.5:1"

Every parameter

Read from apps/api/params.mjs in the repository, which is the single place the service validates a query string.

Out-of-range values are rejected, not clamped, and the message names the parameter:

curl "https://png.quran.ws/api/v1/image/2/255.png?width=9000"
# {"error":"width must be between 64 and 8000, got 9000"}

0, false, no and off all read as false for justify and basmalah. Any other value is true.

The basmalah switch

For this service the basmalah rule is concrete, because it only ever serves Ḥafṣ:

• A range starting at ayah 1 opens with the basmalah, as the plate does.
• In al-Fātiḥa the basmalah is ayah 1, so /1/1.png is the basmalah by itself.
• At-Tawbah, surah 9, has none. GET /api/v1/surahs/9 reports "has_basmalah": false.

Pass basmalah=0 when you are composing a range into a design that already carries one.

Caching, and the v parameter

Renders are cached server-side and every response carries an ETag, so a conditional request costs you a 304.

curl -s -D - -o /dev/null "https://png.quran.ws/api/v1/image/2/255.png?v=3" | grep -i 'cache-control\|etag'
# cache-control: public, max-age=31536000, immutable
# etag: "hpOQJwwEfZQModXXT1FHhaLjcI4"

Without v, the response is cacheable but short-lived and revalidates, so a layout correction reaches you. With v, it is immutable for a year. Pin it when the image is embedded in something that must not change under you — a printed document, a published asset, a design file someone else owns.

Response headers worth reading

x-quran-lines and x-quran-words are useful before you commit to a layout: the same range is 5 lines under layout=fit&aspect=wide and 6 lines under the plate, which is enough to change whether it fits your card.

Limits

• Rate limit. Requests are limited per IP; over the limit you get 429 with {"error":"too many requests, slow down"}. The service's own default is 120 requests a minute, but it is set by an environment variable, so the deployed number is not something you can read from outside. Treat a 429 as expected, back off, and throttle a bulk export yourself.
• Errors are JSON, not images. Every rejection is a 400 with {"error": "..."} and content-type: application/json. Check the status before you write the body to a .png file — otherwise you get a file that is JSON with a PNG extension, and it will fail somewhere much later.
• width is PNG only. SVG and PDF are vector; scale them at use.
• No riwayah, no translation, no tafsīr. Only Ḥafṣ artwork.

Related blocks

How this works

The service holds no font. It loads the word and mark shapes that Quran SVG Elements publishes — the same decomposition of the KFGQPC Madani plates, keyed surah:ayah:word, 77,432 words for Ḥafṣ — and a render collects the shapes in your range and translates them onto a new canvas; PNG is that SVG rasterised, PDF the same vector, page-sized. It runs as a live HTTP service at png.quran.ws, and the same picker also runs as a Canva side panel.