Render a URL
GET /api/v1/render is a URL that returns an image, for an img tag on your own site.
https://pixloom.dev/api/v1/render?prompt=cozy+bookstore+at+sunset&style=watercolor&key=pk_live_...The first request generates the image and takes a few seconds. Every request after redirects straight to the finished file. No polling, no job, no JSON.
This is the endpoint for an <img> or a srcset on your own site, where the prompt changes from page to page.
Put a publishable key in the URL, never a secret one: URLs end up in logs, browser history and other sites' referrer data, so a URL with sk_live_ in it gets a 400. A publishable key only works from the domains you list on it. From a server, send a secret key in the Authorization header instead. For an email, Slack or a CMS field, where there is no domain to check, use the image proxy, which takes no key at all.
Parameters
| Param | Type | Default | Notes |
|---|---|---|---|
prompt | string | required | Missing gives a 400. |
style | string | none | A preset, or one of your own styles. Anything else is a 404 and generates nothing. |
strength | number | 1 | 0 to 1. |
character | uuid | none | |
width | integer | 1024 | Clamped to 256 to 2048, rounded to a multiple of 64. |
height | integer | 1024 | Same. |
format | png, jpeg or webp | webp | Anything else becomes webp. |
age | string | none | Comma-separated kids, bigkids, adults. Unknown values are dropped. |
key | string | A publishable key, when you cannot set a header. Secret keys are refused here. |
Unlike generate, out-of-range numbers are clamped rather than rejected. An image tag cannot handle a validation error, so it gets the nearest sensible image instead.
Character requests follow the character's saved match or lock behavior. The first image of a character in a new look can take a little longer; later ones are quicker. Change the character's photos and its next images follow the new ones.
What you get back
Always a 302 to the image, cached for ten minutes. If we already have a good image for this URL, you get it straight away and it costs nothing. Only a brand new image costs a generation, so a popular URL is almost always a redirect to a file we already have.
Running out of generations
A page that has been running for a while keeps showing images after you hit your limit: if you already made this image, you still get it. You only see a 402 when there is nothing to show.
Responses
| Status | Body |
|---|---|
302 | Redirect to the image. |
400 | Missing prompt, invalid character UUID, or a secret key in the URL. |
401 | Missing or invalid key. |
402 | Out of generations and no earlier image to fall back on. |
403 | Account not approved, or a domain that is not on the key. |
404 | Style, character or permalink not found, or belongs to another account. |
429 | Over your per-minute rate limit. |
502 | Character references could not be read, or image generation failed. Try again. |
503 | New images are paused for a while. Retry after Retry-After seconds. |