API reference
Generate an image with a URL. Embed it with a standard HTML image tag.
Quick start
<img src="https://placeholdr.dev/600x400/minimalist%20modern%20office?seed=3" width="600" height="400"
alt="Minimalist modern office" />
A finished image returns immediately. A new combination returns a
202 temporary SVG. Wait a few seconds and request the
same URL again. A plain image tag does not automatically refresh.
URL format
https://placeholdr.dev/{width}x{height}/{prompt}?style={style}&seed={seed}| Parameter | Accepted values | Default |
|---|---|---|
| width, height | Integers from 64 to 2048 pixels, any aspect ratio | Required |
| prompt | URL-encoded text; up to 120 Unicode characters after normalization | space |
| style | photographic, artistic, anime, oil-painting, 3d-render, cartoon | photographic |
| seed | 1, 2, or 3 | 1 |
Prompts are lowercased, whitespace is collapsed, and unsupported
symbols are removed. Letters and numbers from all languages are
accepted. Longer prompts are truncated. Use
encodeURIComponent(prompt) when constructing a URL in
code.
Size, format, and repeatability
New images are JPEGs. Older saved images may be PNG or WebP; the
Content-Type header identifies the actual format. There
is no format selector.
Smaller images are resized from a larger generated image. Wide or tall requests are cropped to fit your exact dimensions. Each size is a separate image identity, so changing dimensions can change the composition.
Use 64 pixels or more per side for small avatars and simple subjects. For detailed scenes, use at least 128 pixels per side. Previously generated smaller images remain available at their existing URLs.
Finished images are saved once with a one-year immutable cache policy. Equivalent normalized URLs share an image. Existing saved images are preserved across generator updates; an image that has never been generated may reflect a newer model or workflow.
HTTP responses
| Status | Meaning | What to do |
|---|---|---|
| 200 | Finished image | Display and cache it |
| 202 | Queued or running; temporary SVG | Wait at least 5 seconds, then reload the same URL |
| 304 | Your ETag still matches | Use your cached image |
| 400 | Invalid input | Correct the URL |
| 404 | HEAD for an unsaved image | GET the image URL to request generation |
| 429 | Generation limit or queue capacity reached | Wait for the Retry-After duration |
| 503 | Temporarily unavailable | Check status and retry later |
Temporary and failed responses use
Cache-Control: no-store. Retry-After is in
seconds. Automated clients should honor it, use bounded retries, and
stop polling after a few minutes.
HEAD never creates work.
If-None-Match supports revalidation. Cross-origin GET,
HEAD, and OPTIONS are supported.
X-Placeholder-Origin reports edge,
r2, pending, or error.
Usage and privacy
This free service is intended for prototypes, demos, and development. Hotlink the image URL directly. Generate and check your images before a presentation or public demo; save a local copy if your project needs independent availability.
The free allowance is 30 new images per day per IP address, with up to 10 new images per minute. Daily limits reset at 00:00 UTC. Loading saved images or checking an existing generation does not count toward this allowance. A new generation counts when accepted, even if it later fails.
New generation is subject to shared service capacity.
If your allowance or shared capacity is reached, the
API returns 429 with a Retry-After header. Saved images
remain available when generation limits are reached.
Need higher limits or an API key? Contact us at hello@placeholdr.dev.
Prompts are part of public URLs and are stored with images. Do not include secrets or personal information. Request analytics include prompt, dimensions, style, outcome, timing, and the referring hostname when supplied. Admission uses a short-lived hash of the client IP address. Site visit and copy events use Google Analytics.
AI outputs can be inaccurate or unsuitable. Review them before sharing, and make sure your use respects others' rights. The service does not provide a rights-clearance or uptime guarantee.
Troubleshooting
If you still see the temporary image, reload the same URL after the indicated wait. Changing the prompt or seed requests another image. If a proxy rejects the temporary SVG, use a regular image tag as shown in the recipes, or generate and save the image first.
Check current service diagnostics for storage and generation availability.