# sampleimg.com

sampleimg.com is a free, stateless Developer Image Toolkit. It generates placeholder images, deterministic mock images, QR codes, OG images, avatars, charts, and pixel art from URL parameters. No API key is required.

Base URL: https://sampleimg.com
All examples use the Base URL. Images are cacheable and no database or external image-generation API is required.

## Placeholder images

GET https://sampleimg.com/{width}x{height}

Examples:
- https://sampleimg.com/800x450
- https://sampleimg.com/800x450?text=Hello&bg=4a90e2&fg=ffffff
- https://sampleimg.com/800x450?format=svg

Limits: width and height are 1-4096 pixels; total area is at most 4,194,304 pixels; text is 1-100 Unicode characters when specified (explicit empty text is rejected). Colors are 3- or 6-digit hexadecimal values, with or without #.

Supported placeholder parameters include bg, fg, text, fontSize (1-512), weight, align, valign, radius, border, borderColor, padding, lineHeight, letterSpacing, gradient, angle, stops, noise, pattern, patternColor, and format.

format accepts svg, png, jpeg, and webp. SVG is returned for svg; PNG is returned for png, jpeg, and webp because JPEG/WebP encoding is not yet available.

## Deterministic mock images

Use seed to generate the same design for the same size, seed, style, and parameters. The default style is gradient.

- https://sampleimg.com/600x600?seed=product-123
- https://sampleimg.com/600x600?seed=product-123&style=mesh
- https://sampleimg.com/600x600?seed=product-123&style=geometric
- https://sampleimg.com/600x600?seed=product-123&style=waves

Styles: gradient, mesh, geometric, waves. Seed is limited to 200 Unicode characters. Seed backgrounds are generated locally with a hash and pseudo-random generator; no random value is used per request.

## Presets

- OG / 1200x630: https://sampleimg.com/og?text=Hello
- Product / 1200x1200: https://sampleimg.com/product?seed=product-123
- YouTube / 1280x720: https://sampleimg.com/youtube?text=Hello
- Avatar / 512x512 alias: https://sampleimg.com/avatar?seed=user-123

The legacy OG template remains available with a title: https://sampleimg.com/og?title=Blog%20Post&description=Great%20content
The legacy avatar path remains available: https://sampleimg.com/avatar/user-123?size=256

## Other endpoints

- QR: GET https://sampleimg.com/qr?data=https://example.com&size=256&format=png (data required, maximum 1024 Unicode characters; size 64-1024; SVG or PNG; default PNG)
- Chart: GET https://sampleimg.com/chart?type=bar&data=10,20,15 (type bar or line; 2-50 numeric values; width/height 200-4096 with a 4,194,304-pixel area limit; default PNG)
- Pixel art: GET https://sampleimg.com/pixel?preset=heart&size=256 (presets heart, smiley, check, arrow, star, x; custom Base64 data max 512 decoded bytes; SVG or PNG; default SVG; size 64-2048)

## Overlay images

Add `overlay=https://...` to a placeholder image to embed a remote image. Only HTTP(S) URLs without userinfo and up to 2048 characters are accepted. Localhost, loopback, private, and link-local destinations are rejected and redirects are not followed; the response must use a supported image Content-Type (PNG, JPEG, GIF, WebP, or SVG) and be at most 2 MB. The fetch timeout is 5 seconds. DNS rebinding cannot be completely prevented by the Worker alone, so use trusted public image hosts. Optional controls are `overlayX` (`left`, `center`, `right`, or numeric px), `overlayY` (`top`, `middle`, `bottom`, or numeric px), `overlayWidth`, `overlayHeight` (`auto`, positive px, or percentage), and `overlayOpacity` (0-1). The Worker and Cloudflare edge are configured for a one-hour overlay cache lifetime; a zone-level Browser Cache TTL may change the client-facing header. Normal images use an immutable long cache. Invalid overlay URLs return 400; oversized, failed, and timed-out fetches return 413, 502, and 504 respectively.

## Error behavior

- Invalid or missing parameters return HTTP 400 JSON: {"error":"..."}.
- Unsupported overlay content returns 400.
- Oversized overlay responses return 413.
- Overlay network failures return 502; overlay timeouts return 504.
- Successful image responses return an image Content-Type and cache headers.

## AI coding use case

For deterministic product placeholders, use:
```tsx
products.map((product) => (
  <img
    src={`https://sampleimg.com/product?seed=${product.id}`}
    width={1200}
    height={1200}
    alt={product.name}
  />
))
```

## Machine-readable documentation

OpenAPI: https://sampleimg.com/openapi.json
Human/developer homepage: https://sampleimg.com/