The image proxy
GET /api/img/{handle}/{name} is a permanent public URL for a named image, with no key in it.
<img src="https://pixloom.dev/api/img/acme/hero" alt="Hero image" />This is the URL to put on a public page. There is no key in it: your account handle identifies you, and the permalink name identifies the image. Give it to a CMS, an email template, a designer, anyone.
You create the name in the dashboard under Permalinks, where you also set its prompt, size, style and how often it refreshes. Permalinks explains them without the API detail.
The URL
https://pixloom.dev/api/img/{handle}/{name}
https://pixloom.dev/api/img/{handle}/{name}/{style}
https://pixloom.dev/api/img/{handle}/{name}/{style}?age=kids| Part | Notes |
|---|---|
handle | Your account handle. Set it in Settings. |
name | The permalink name. |
style | Optional. A preset or one of your own styles. Ignored if the permalink is style locked. Anything else is a 404, never a new image. |
?age= | Optional. Comma-separated kids, bigkids, adults. Overrides the permalink's audience. |
The same name with different styles gives you a set of matched images: one prompt, many looks, each cached on its own.
Keeping it to your own site
Add domains to the key behind your handle and we check the browser's Referer on every load. A request from anywhere else gets a 403 and no image. Leave the domain list empty and the URL works anywhere, which is what you want for email.
Localhost always passes, so this works in development without any setup.
The rule it follows
Never make a visitor wait when an image exists. The dashboard's Live now panel always agrees with what this URL serves.
- Pinned images win. Pin some and the URL serves only those, rotating on the refresh window. Nothing new is made.
- Otherwise it serves an image it already has in the style asked for, and keeps it fresh for you when the refresh window passes. Visitors never wait for the refresh.
- The first visit to a new permalink or style makes the image. That is the only time anyone waits.
A permalink with no domain lock is answered from the edge for up to a minute, so a page that goes viral stays fast. It rotates to a new image at most once a minute, and views answered from the edge do not show in your view counts.
Every image it makes counts against your own plan, like any other generation. A busy page costs you no more than a quiet one, and a permalink set to never refresh never spends a generation. Permalinks covers pinning, refresh and styles.
Responses
| Status | Body |
|---|---|
302 | Redirect to the image. |
403 | The page's domain is not on your key. |
404 | { "error": "Account not found" } for an unknown handle, { "error": "Shortcut not found" } for an unknown name, { "error": "Style not found" } for a style that is not a preset or yours. |
429 | One visitor loaded too many images, or asked for too many new ones, in a minute. Normal browsing never gets here. |
Compared to render
Render takes a prompt in the URL and needs a publishable key locked to your domains. The proxy takes a name and needs no key. Use render for private, one-off, machine-generated URLs. Use the proxy for anything a visitor's browser will request.