Embed guide
One script tag. After that, any image on the page can describe itself.
The script tag is the fastest way to use Pixloom. You add it once, and from then on you write image tags with a prompt instead of a file.
<script src="https://pixloom.dev/pixloom-client.js" data-key="pk_live_..."></script>
<img data-pixloom-prompt="a lighthouse in fog" data-pixloom-style="cinematic" alt="A lighthouse in fog" />The script looks for Pixloom attributes when the page loads and keeps watching, so images added later by React, Vue, a CMS, or plain JavaScript work too.
What happens on the first load
The first visitor to ask for a prompt waits a few seconds while the image is made. A shimmer marks the spot. Everyone after that gets the finished image from cache, on any page and any site that uses the same prompt and style.
If you give the tag a src, that picture shows until the generated one is ready. Good for a logo or a placeholder you already have.
The attributes
| Attribute | What it does |
|---|---|
data-pixloom-prompt | The picture, in words. Required, unless you use a permalink. |
data-pixloom-style | A style name, like watercolor. Optional. |
data-pixloom-mode | generate (the default) makes an exact image. instant serves the closest library image right away and never generates. |
data-pixloom-width, data-pixloom-height | Pixels, 256 to 2048. Default 1024. |
data-pixloom-format | webp (default), png, or jpeg. |
data-pixloom-permalink | The name of a permalink from your dashboard, instead of a prompt. Change the image there, and every page updates. |
data-pixloom-character | A character ID, so the same person or mascot appears every time. |
data-pixloom-age | Who the picture is for: kids, bigkids, or adults. Optional. |
You can also set a default mode for the whole page with data-mode="instant" on the script tag itself.
When the script does not load
An ad blocker, a bad network, or a strict content policy can stop the script running. Nothing on your page breaks: the browser renders each <img> with whatever src you gave it, because the Pixloom attributes are inert without the script. A tag with no src shows nothing at all, and your alt text stands in.
So the rule is simple. If the picture is decoration, leave the src off. If the page would look broken without a picture there, give the tag a src you already host, and Pixloom swaps it once the real image is ready.
The same holds if the API is reachable but a single image fails. The script hides its shimmer and leaves the fallback in place rather than showing a broken image.
<!-- Degrades to your own placeholder -->
<img src="/img/hero-placeholder.jpg" data-pixloom-prompt="a lighthouse in fog" alt="A lighthouse in fog" />Images you asked for by prompt are also cached in the browser for two hours, so a repeat visitor sees them immediately, before the script has talked to the API at all. Set data-cache-ttl in milliseconds on the script tag to change that, or data-cache="false" to switch it off. Permalinks are never cached this way, so that changing one takes effect at once.
Refresh and rotation
A permalink can stay on one image or move on by itself. Set its Refresh to every day and it makes a fresh image daily; pin a few images and it rotates through only those. Permalinks has the full rules, and each permalink's dashboard page shows which image is live.
Rotation propagates straight away. Permalink URLs are served no-store, and the browser cache described above only applies to prompts, never to permalinks, so the moment you change the image in the dashboard the next request gets it.
Instant or generate?
Instant is for pages that need a picture now and are fine with a close match. It costs nothing against your monthly quota and works on the free plan. When the library has nothing close, your original src stays.
Generate is for pages where the picture has to be exactly what you asked for. It uses one generation per new prompt, and after that it is cached like everything else.
Where your images are seen
The script tells Pixloom which page each image appeared on, as the site and path only, never the query string. Open any image in your dashboard and the lightbox says where it was seen in the last 30 days, with a link to each page. Images served by URL, without the script, show the site alone, because browsers drop the path when they send a referrer across domains.
The key is public. Is that OK?
Yes. A publishable key can only fetch images, and only from the domains you list when you create it. Someone who copies it from your page source gets nothing useful. Keep secret keys, the ones starting sk_live_, on a server.