PlaceMellon › Reference

PlaceMellon Reference

Request an image at the size your layout uses. Add a category or visual treatment, then use the address in your page or save the image with your project.

On This Page

Image URLs

Request	Response
`GET /{width}/{height}`	An image at the requested width and height.
`GET /{size}`	A square image.
`GET /g/{width}/{height}` `GET /g/{size}`	A grayscale photo. Equivalent to adding `?gray`.

Dimensions are whole numbers from one to 2048 pixels. Without options, the response is a JPEG photo. Put a file extension after the last dimension to request another supported format.

https://placemellon.andrew.cmu.edu/400/300.webp?category=labs&gray

Parameters

Start the query string with ? and separate options with &. Flags are enabled by their presence: ?random=false still requests a random photo.

Parameter	Accepted Value or Effect	Default
`category`	A category value. Photos only.	All categories
`random`	Flag. Select a photo on each request. A value like `random=1` distinguishes addresses; it is not a seed or photo ID.	Consistent selection
`gray`, `grayscale`	Flag. Convert a photo to grayscale. The `/g/` prefix also works.	Color
`scotty`	Flag. Draw the Scotty graphic.	Photo
`gradient`	Flag. Add a white-to-gray background to the Scotty graphic. Requires `scotty`.	Transparent
`profile`	Flag. Draw a round Scotty profile picture. A rectangular request redirects to a square using the smaller dimension.	Photo
`bio`	Flag. Draw the gray stacked-wordmark bio placeholder.	Photo
`solid`	Flag. Fill the image with a CMU brand color.	Photo
`color`	A color value. Requires `solid`.	`iron-gray`
`text`	Flag. Show the width × height on a solid placeholder. Requires `solid`.	No dimensions

Choose at most one of scotty, profile, bio and solid. Photo options (category, random and grayscale) do not combine with those image types. Supply category and color once each. Unknown parameter names are rejected.

Category Values

Category	Value
Campus	`campus`
Classrooms	`classrooms`
Labs	`labs`
Life	`life`

Color Values

Use these values with ?solid&color=. The colors follow CMU's brand palettes.

Color	Value	Hex	Palette
Carnegie Red	`carnegie-red`	`#c41230`	Core
Black	`black`	`#000000`	Core
Iron Gray	`iron-gray`	`#6d6e71`	Core
Steel Gray	`steel-gray`	`#e0e0e0`	Core
White	`white`	`#ffffff`	Core
Scots Rose	`scots-rose`	`#ef3a47`	Tartan
Gold Thread	`gold-thread`	`#fdb515`	Tartan
Green Thread	`green-thread`	`#009647`	Tartan
Teal Thread	`teal-thread`	`#008f91`	Tartan
Blue Thread	`blue-thread`	`#043673`	Tartan
Highlands Sky Blue	`highlands-sky-blue`	`#007bc0`	Tartan
Machinery Hall Tan	`machinery-hall-tan`	`#bcb49e`	Campus
Kittanning Brick Beige	`kittanning-brick-beige`	`#e4dac4`	Campus
Hornbostel Teal	`hornbostel-teal`	`#1f4c4c`	Campus
Palladian Green	`palladian-green`	`#719f94`	Campus
Weaver Blue	`weaver-blue`	`#182c4b`	Campus
Skibo Red	`skibo-red`	`#941120`	Campus

File Types

Image	Default	Accepted Extensions
Photos	JPEG (`image/jpeg`)	`.jpg`, `.webp`
Scotty, Profile Pictures, Bio Placeholders and Solid Colors	SVG (`image/svg+xml`)	`.svg`, `.png`

The extension belongs on the final dimension, before the query string: /400/300.webp?gray or /400/300.png?solid&text. PNG is image/png; WebP is image/webp. Unsupported image type and format combinations return an error.

Embedding and Downloads

Use an image URL in HTML, with & between query parameters:

<img src="https://placemellon.andrew.cmu.edu/400/300?category=labs&amp;gray"
     width="400" height="300" alt="Placeholder photo of a CMU lab">

For several random photos on one page, use distinct addresses like ?random=1 and ?random=2. A browser can reuse one response for images with the same address.

To keep an image with your project, download the response. Quote the URL so the shell preserves its query string:

curl --fail --show-error 'https://placemellon.andrew.cmu.edu/400/300.webp?category=labs&gray' \
  --output placeholder.webp

Find the Original Photo

Photo responses include an X-Photo header with the source filename. Look up that name in CMU Selects to download the full photo for a finished page. Graphics do not have this header.

curl --fail --show-error --head 'https://placemellon.andrew.cmu.edu/400/300?category=campus'

In a browser, open the image request in the developer tools' Network tab and read its response headers. For a random photo, inspect the request that produced the image you see; another request can select a different photo.

Selection and Caching

The size and category determine the default photo selection. Wide requests favor landscape photos, tall requests favor portraits and near-square requests use either. If a category has no photos of the preferred orientation, PlaceMellon uses the available photos. The result is cropped to fill the requested dimensions.

Adding or removing source photos can change the selection. Save the response if you need to preserve an exact image.

Nonrandom images are cached in memory, and responses allow browser caching for up to a day. Random photos skip both caches and return Cache-Control: no-store. Development responses also use no-store.

Errors

Status	Meaning	What to Check
400	Invalid size, parameter or combination.	Read the plain-text response. Check dimensions, parameter names, image type and extension.
404	Unknown category, color or route.	Use a value from the category or color table and a supported URL path.
502	The source image could not be fetched or rendered.	Try again shortly. If it keeps happening, report the image URL on GitHub.
503	Photos are still loading or the selected category has no photos.	Retry later or choose a different category. Graphics do not need the photo catalog.

Check the status and content type before saving a response as an image. GET /healthz returns JSON with the total photo count, category counts and refreshedAt; its status is 200 when the catalog contains photos or 503 when empty.

To set up an AI coding agent, use the prompt on the home page.