Appearance
The IIIF Image API is a URL grammar for getting exactly the slice, size, rotation, and format of an image you want, straight from the address. Every request follows one template — {identifier}/{region}/{size}/{rotation}/{quality}.{format} — and once you can read those five segments you can crop, scale, rotate, and convert any conformant image without a single line of code.
What does a IIIF Image API URL look like?
Here is the full grammar with a worked example beneath it:
{scheme}://{server}/{prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}https://images.example.org/iiif/3/manuscript_07/full/max/0/default.jpgThat asks for the whole image (full), at the largest size the server allows (max), unrotated (0), in default colour (default), as JPEG. Change any segment and you get a different derivative. There is no separate API call to learn — the URL is the API.
How do I crop a region?
The region segment accepts four shapes. Pixel coordinates are x,y,w,h:
.../1200,800,1024,768/max/0/default.jpg # 1024×768 crop starting at (1200,800)
.../pct:25,25,50,50/max/0/default.jpg # the centre 50% by percentage
.../square/max/0/default.jpg # largest centred square
.../full/max/0/default.jpg # the entire imagePrefer pct: when you want a crop that stays meaningful even if the master is re-digitised at a different resolution.
How do I control the output size?
The size segment scales whatever region you selected:
size value | Meaning |
|---|---|
max | Largest the server will deliver |
200, | 200 px wide, height proportional |
,300 | 300 px tall, width proportional |
400,300 | Exactly 400×300 (may distort) |
pct:50 | Half the region's dimensions |
^max | Allow upscaling above native (v3, if extraFeatures permits) |
For a thumbnail, the idiomatic call is .../full/200,/0/default.jpg. The trailing comma is load-bearing: 200, means "200 wide, auto height".
How do rotation, quality and format work?
.../full/max/90/default.jpg # rotate 90° clockwise
.../full/max/!0/default.jpg # mirror horizontally (the ! prefix)
.../full/max/0/gray.jpg # greyscale, useful for legibility
.../full/max/0/bitonal.png # 1-bit black and white
.../full/max/0/default.tif # lossless TIFF for analysisdefault keeps the image's natural colour. Use gray to study faded ink, bitonal for line drawings, and png/tif when you need lossless pixels for measurement or OCR.
How do I know what a server supports?
Read info.json first. It tells you the dimensions, allowed sizes, tile structure, and the compliance level:
bash
curl -s https://images.example.org/iiif/3/manuscript_07/info.json | python -m json.toolKey fields to check:
width/height— the true pixel dimensions; never request larger.maxWidth/maxHeight/maxArea— caps that silently clamp big requests.profile— the compliance level (level0,level1,level2); level0 only serves the exactsizeslisted.extraFeatures— whether mirroring, rotation by arbitrary degrees, or upscaling are allowed.
If your perfectly formed request returns a smaller image than you asked for, a max* cap is almost always the reason — not a bug.
A short, reliable workflow
- Fetch and skim
info.jsonto learn dimensions and caps. - Build the URL one segment at a time, starting from
full/max/0/default.jpg. - Add a region crop, test it in a browser, then constrain size.
- Choose format last:
jpgfor web,png/tiffor downstream processing. - Cache the resulting URLs — they are stable, shareable and bookmarkable.
Key Takeaways
- One URL template covers everything:
{id}/{region}/{size}/{rotation}/{quality}.{format}. - Neutral values are
full,max,0,default— start there and adjust. - Use
pct:regions and sizes for crops that survive re-digitisation. 200,means width 200, auto height; the comma matters.- Always read
info.jsonfor dimensions,max*caps and the compliance profile. - A clamped response is the server enforcing
maxWidth/maxArea, not an error.
Frequently Asked Questions
What are the five parameters in a IIIF Image API URL?
Region, size, rotation, quality and format, in that order: {identifier}/{region}/{size}/{rotation}/{quality}.{format}. Each segment is required; use full, max, 0 and default as the neutral values.
How do I request a thumbnail with the Image API?
Use full for region and a width-constrained size such as 200, leaving height blank: .../full/200,/0/default.jpg. The comma after 200 means 'scale to 200px wide, height automatic'.
What is the difference between size max and full?
full as a region means the whole image; max as a size means the largest the server will deliver, which may be capped below native resolution by maxWidth in info.json. They control different URL segments.
How do I crop a specific area of an image?
Put pixel coordinates in the region segment as x,y,w,h, for example 1000,500,800,600. Use pct: for percentage-based crops that survive resolution changes.
Why does my size request return a smaller image than asked?
The server enforces maxWidth, maxHeight or maxArea from info.json. Requests above those limits are silently clamped, so check the profile and sizes block before assuming a bug.
Which format and quality should I default to?
default for quality and jpg for format suit most web delivery. Use gray for legibility studies and png or tif when you need lossless output for analysis.