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.
TTL and rotation
A permalink normally points at one image and stays there until you pick a different one in the dashboard. That is the default, and it is what you want for a logo or a hero you have approved.
Give a permalink a TTL instead and it rotates on its own. Once the TTL elapses, the next request serves a different image from your library for that permalink, and the clock restarts. A recipe site can point sidebar-dish at a TTL of a day and get a new dish every day without touching the page.
Rotation is per permalink and per style, so sidebar-dish in watercolor and sidebar-dish in cinematic each keep their own current image and their own clock.
Pinning changes what rotation draws from rather than stopping it. Pin one or more images on a permalink and it only ever serves those, and never generates anything new. Pin a single image and you have frozen the permalink; pin six and you have a hand-picked rotation.
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.
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.
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.