API docs
A JSON catalog and an image endpoint. Previews need no key. Full-size files need a key and a plan.
Quick start
# List breeds curl https://dogimage.dev/api/v1/breeds # A free 1024 px preview curl -L "https://dogimage.dev/api/v1/images/<breed>/default/front-left?size=1024" -o dog.webp # The full-size transparent PNG (2048 px), with your key curl "https://dogimage.dev/api/v1/images/<breed>/default/front-left?size=full" \ -H "Authorization: Bearer $DOG_IMAGE_API_KEY" -o dog.png
JavaScript
const { breeds } = await fetch("https://dogimage.dev/api/v1/breeds").then((r) => r.json());
const src = "https://dogimage.dev/api/v1/images/" + breeds[0].slug + "/default/front-left?size=512";Python
import os, requests
r = requests.get(
"https://dogimage.dev/api/v1/images/pug/default/front-left",
params={"size": "full"},
headers={"Authorization": "Bearer " + os.environ["DOG_IMAGE_API_KEY"]},
)
r.raise_for_status()
open("pug.png", "wb").write(r.content)
print(r.headers["X-Quota-Remaining"])Step-by-step guides: React, Next.js, Python, Node.js, curl, and more.
Endpoints
| Request | Key | Returns |
|---|---|---|
GET /api/v1/breeds | No | Every breed, its variants and the views |
GET /api/v1/breeds/{breed} | No | One breed with preview links for every view |
GET /api/v1/images/{breed}/{variant}/{view}?size=512|1024 | No | A redirect to the WebP preview |
GET /api/v1/images/{breed}/{variant}/{view}?size=full | Yes | The 2048 px transparent PNG |
GET /api/v1/usage | Yes | Files used and left this month |
variant is a color slug from the catalog, or default for the breed's main set. view is one of: front, front-left, left, rear-left, rear, rear-right, right, front-right, head.
Keys and limits
Create a key on your account page. It is shown once. Send it as Authorization: Bearer <key>, from your server only.
A plan counts distinct full-size images per calendar month (UTC). Fetching the same image again in the same month is free. Starter: 200 images a month. Pro: 700 images a month. All images: every image a month. Each full-size reply carries X-Quota-Limit, X-Quota-Used and X-Quota-Remaining (unlimited on the All images plan).
Full-size files are meant to be downloaded and stored on your side. Do not hot-link them in pages.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_size | size is not 512, 1024 or full |
| 401 | missing_or_invalid_key | No key, or a revoked one |
| 402 | no_active_plan | The key's account has no active plan |
| 404 | unknown_breed, unknown_variant, unknown_view | The reply lists the valid choices |
| 429 | quota_used_up | All files of the month are used |
| 502 | file_unavailable | The file could not be fetched. It was not counted |
| 503 | plan_check_failed | The plan could not be checked. Retry |
About the images
The images are AI-generated. Each set passes an automatic check of its nine views before it is published, and we keep reviewing sets by hand after that. Coats follow common descriptions of the breed. They are illustrations, not records of any real dog or a breed standard.
Browser apps on other sites may read the two breeds endpoints and load preview files. Keep the key, and full-size downloads, on your server.
Machine-readable: OpenAPI, llms.txt, llms-full.txt and pricing.md.