Breed placeholder images for shelter and adoption sites

When a shelter listing has no photo yet, show a breed illustration with a clear label that says it is not the animal. Keep it visually different from a real photo, and use the catalog's crossbreed field to treat mixes honestly. Replace it the day a real photo arrives.

What a placeholder is for

An intake record can exist days before anyone takes a good photo. During that window the listing page still needs a card in the grid. Without a picture, listings with no photo get skipped. With a wrong picture, you mislead the person who clicks. A labeled placeholder avoids both.

The line you must not cross: the placeholder is not the dog. The catalog images are AI-generated illustrations of one adult dog per set. They are not photos, they show no real animal, and they are not a breed standard. A mixed-breed dog that "looks like" a Beagle on the intake sheet will not look like the illustration, and an adopter should never find that out at the meeting.

Make the difference obvious

Three small choices keep the placeholder honest:

• A caption on the image, inside the card and not hidden in a tooltip: "Breed illustration. Photo coming soon."
• A different frame. Give it a dashed outline or a flat tinted background, so a grid of real photos never blends with it. The images have a transparent background, so a flat color shows through.
• No name tag on the dog. Do not overlay the animal's name on the illustration. The name belongs to the card text.

Use the front-left view for a card, because it shows the whole dog from a natural angle. Use head for a compact list or for an email.

Mixed breeds and crossbreeds

Many shelter dogs are mixes, and the intake form often records a guess. Each breed in the catalog has a crossbreed boolean. Entries such as the cockapoo, the goldendoodle and the puggle are marked as crossbreeds. A few rules help:

• If the guess matches a crossbreed entry, use it and add "Mix" to the label.
• If the guess is a purebred, show that breed's illustration and write "Possible breed mix" in the label. A guess is not a fact.
• If the mix does not match any entry, or the staff do not know, do not pick the nearest. Show a plain "No photo yet" card.

Do not put breed guesses in a headline that reads like a fact. "Beagle mix" with an illustration labeled as a breed illustration is fine. "Beagle" with the same picture is not.

How to wire it

The listing record keeps a photo URL and an optional breed slug. The page picks one:

const BASE = "https://dogimage.dev";

function listingImage(listing) {
  if (listing.photoUrl) {
    return { src: listing.photoUrl, alt: listing.name, isPlaceholder: false };
  }
  if (listing.breedSlug) {
    return {
      src: `${BASE}/api/v1/images/${listing.breedSlug}/default/front-left?size=512`,
      alt: "Breed illustration",
      isPlaceholder: true,
    };
  }
  return { src: null, alt: "No photo yet", isPlaceholder: true };
}

The markup for a placeholder card includes the label and the credit link, which the free preview requires:

<figure class="listing-photo placeholder">
  <img src="https://dogimage.dev/api/v1/images/beagle/default/front-left?size=512"
       alt="Breed illustration" width="320" height="320">
  <figcaption>Breed illustration, not this dog. Photo coming soon.
    <a href="https://dogimage.dev/dogs/beagle">Beagle image: Dog Image API</a>
  </figcaption>
</figure>

To populate a breed picker for staff, read GET /api/v1/breeds, keep the slug and show name, with the crossbreed flag as a "Mix" tag. The endpoint needs no key. See the docs for the full reference.

Which plan fits

Previews cover the website. A free plan with a visible credit link on the page is enough for most shelters.

A paid plan matters only if you want full-size files, for example for a printed "photo coming soon" flyer. One image is one view of one set at full size. If your shelter sees 25 breeds regularly, one view each is 25 images, well inside Starter's 200 a month. All 298 default sets in one view is 298 images: two months on Starter, one month on Pro. Check pricing for the current plans.

License points for adoption sites

Preview files may be used with a visible link crediting Dog Image API next to the image or on the same page. Full-size files go in your own site, documents and print with no credit needed. You may not resell the images, republish them as a collection, or use them to build a competing image service. If other shelters ask for your files, point them to the dogs catalog instead of passing them on.

Do not use the images in a way that implies a specific animal, in fundraising copy or elsewhere. The license is a draft not yet reviewed by a lawyer, so read it before you rely on it.